Deploy Astro on Lizard

Astro has two deployment paths on Lizard: serve a static dist/ directory on port 80, or run the standalone Node adapter on port 3000 for on-demand routes. Choose the mode before deploying because the adapter changes both the output and the runtime.

Choose a mode

Both paths use a build script that runs astro build. Commit the lockfile and keep the default dist output path. Detection reads the Astro config and installed dependencies. An unused Node adapter dependency alone does not select the server path. Use literal output and adapter settings; dynamic values, custom output paths, and middleware mode need a Dockerfile.

Configure a Node server

For on-demand pages, add a Node adapter version compatible with your Astro version:

npx astro add node

Check astro.config.mjs:

import { defineConfig } from 'astro/config';
import node from '@astrojs/node';
 
export default defineConfig({
  output: 'server',
  adapter: node({ mode: 'standalone' }),
});

Standalone mode starts its own HTTP server. Middleware mode requires a separate server and does not fit this launch command. Read the Astro Node adapter guide if you need middleware or a mix of prerendered and on-demand routes.

Test locally

npm ci
npm run build

For the Node mode:

HOST=0.0.0.0 PORT=3000 node ./dist/server/entry.mjs

Request a route that actually runs on the server and a built asset. For a static site, use npm run preview locally and inspect the generated route files in dist/.

Deploy

After CLI setup, create the project:

lizard init --name astro-app
lizard add --service web

For the Node adapter:

lizard up --service web --port 3000

For a static site:

lizard up --service web --port 80

Use only the command for your chosen mode. Leave service command overrides unset for lizardpack detection. Read lizard logs --build --service web --json, then check runtime logs and the live URL.

Variables, sessions, and routes

Values used to generate static HTML require a new build when they change. Server code can read runtime variables through the mechanisms supported by your Astro version; configure them in variables and secrets. Browser-visible values must not contain credentials.

If your app uses sessions, choose storage that fits restarts and multiple replicas. Do not rely on the container filesystem as a shared durable store. See storage and recovery.

For a static content site, test a missing URL and use static routes and 404s to return the proper status. If an SSR deployment exits or serves no routes, verify that dist/server/entry.mjs exists, the adapter uses standalone mode, and the service port is 3000.

See tested versions and cloud results for the September 9, 2026 deployment checks and their limits.

Updated September 9, 2026