Deploy an Astro site

An Astro site builds to static HTML by default, and Sevalla publishes it as a static site: the build runs astro build from your Git repository and Cloudflare serves the dist folder. A site that renders pages on demand uses the Node.js adapter and runs as an application instead, which Ingot, Sevalla’s builder, builds and starts with no configuration.

At a glance


Source	A Git repository
Build	Static site: `npm run build` on Node.js Latest LTS, publishing `dist`. Application: Ingot (Node.js 24, npm), or the Dockerfile
Start command	Application: `node dist/server/entry.mjs`, which Ingot takes from the Node.js adapter
Port	Application: the `PORT` environment variable, `8080` by default
Processes	Application: web process
Services	None
Disk	None
Size	Application: H1 for the web process. A static site has no size.

Environment variables

Neither the static site nor the application needs environment variables of its own. Sevalla sets PORT to the application’s web process port.

Before you begin

A Sevalla company with a payment method, and a GitHub, GitLab or Bitbucket account for the repository. See Git providers.
Node.js 24 or later on your computer.

Create the project

Create a project from Astro’s basics template:

npm create astro@latest storefront -- --template basics --yes
cd storefront

The project comes with a .gitignore, a Git repository with a first commit, and a build script that runs astro build.

Prepare the project for Sevalla

A static Astro site needs no changes. astro build writes every page to dist, as about/index.html for /about, which is how a static site serves it. Static sites take the Node.js version from their build settings, not from package.json, and the default, Latest LTS, meets Astro 7’s requirement of Node.js 22.23.4 or later. Run npm run build && npm run preview and open http://localhost:4321 to check the build locally. Then push the repository that create astro made to your Git provider:

git branch -M main
git remote add origin https://github.com/acme/storefront.git
git push -u origin main

Deploy to Sevalla

Choose the repository

In the sidebar, click Static sites, then click Create static site. Under Source, click Private repository, then choose the Git provider, the Repository and the Branch.

Check the build settings

Under Build settings, Sevalla shows Framework detected: Astro and fills in the values. Check them:

Field	Value
Build site before publishing	On
Node version	Latest LTS
Build command	`npm run build`
Root directory	Empty, for the repository root
Publish directory	`dist`

Create the static site

Enter a Name under Details, then click Create static site. Sevalla starts the first deployment right away, and deploys every push to the branch while Auto-deploy is on.

See Build settings for every field.

An application built from the same repository serves the site too: Ingot detects Astro without an adapter, builds dist, and serves it with Caddy, with a one-year cache lifetime for the hashed files under /_astro/. A static site costs nothing up to 100 GB of bandwidth a month, so use an application only when the site needs something only applications have, such as promoting one build through the stages of a pipeline.

Verify the deployment

On the Deployments tab, wait for the deployment’s status to change to Deployed. The site’s Status on the Overview tab changes to Live.
On the Overview tab, click Visit site. The Astro starter page opens on the site’s *.sevalla.page domain, for example storefront-x7k2m.sevalla.page.

Check the page’s title from a terminal:

curl -s https://storefront-x7k2m.sevalla.page/ | grep -o '<title>[^<]*</title>'

<title>Astro Basics</title>

The static site's Details card with its domain, Live status, source repository and the Visit site button

With the API, Get static site deployment (getStaticSiteDeploymentV3) returns the deployment’s status, success once it’s deployed, and Get static site deployment logs (getStaticSiteDeploymentLogsV3) returns its build log, which ends with Static site has been deployed successfully. See Deploy the static site with the API. If the deployment fails, open it on the Deployments tab and read its build log, then see Troubleshoot static sites.

Render pages on demand

Pages that run code for each request, such as API endpoints, authentication or pages that export prerender = false, need a server. Build them with the Node.js adapter and deploy the project as an application. Add the adapter and pin the Node.js version:

npx astro add node --yes
npm pkg set engines.node="24.x"

astro add node installs @astrojs/node and sets the adapter in astro.config.mjs. To render every page on demand, also set output to "server", so that the file looks like this:

astro.config.mjs

// @ts-check
import { defineConfig } from "astro/config";
import node from "@astrojs/node";

export default defineConfig({
  output: "server",
  adapter: node({ mode: "standalone" }),
});

Setting	Why
`output: "server"`	Renders every page on demand. Leave it out to keep pages static except those that export `prerender = false`.
`mode: "standalone"`	`astro build` writes a server to `dist/server/entry.mjs`.
`engines.node`	The template’s `>=22.23.4` lets Ingot pick its default line, Node.js 24 today, which a new Ingot release can move. `24.x` keeps the build on Node.js 24. See Pin the Node.js version.

The project needs no start script and no server.host setting. Ingot detects the adapter, starts the web process with node dist/server/entry.mjs and sets HOST to 0.0.0.0, so the server listens on all network interfaces. It takes its port from PORT, which Sevalla sets to the web process’s port (8080 by default). The deployment’s build log shows Ingot’s build plan:

Build log

╭─ ■ Astro (Node adapter) · Node.js 24 ────────────────────────────────────╮
│ Node.js          24                          package.json engines "24.x" │
│ Package manager  npm                         package-lock.json           │
│ Framework        Astro (Node adapter)        package.json                │
│ Start            node dist/server/entry.mjs  Astro (Node adapter)        │
├─ Image ──────────────────────────────────────────────────────────────────┤
│ Build            node:24-trixie                                          │
│ Runtime          node:24-trixie-slim                                     │
│ User             1000:1000                                               │
│ Init             tini                                                    │
│ Port             $PORT, default 8080                                     │
╰─────────────────────────────────────────────────────────── Ingot v0.5.0 ─╯

Commit and push the changes:

git add .
git commit -m "Render pages on demand"
git push

Then create the application. These steps build with Ingot. To build from your own Dockerfile instead, see Deploy with a Dockerfile.

Create the application

In the sidebar, click Applications, then click Create > Application. Under Source, click Private repository, then choose the Git provider, the Repository and the Branch. Under Location, choose a Data center. Keep the Size at H1 or choose a larger one, then click Create application. The application opens on its Overview tab with the status Not deployed yet: creating an application doesn’t deploy it.

Deploy

Click the Overview tab, then click Deploy now under Recent deployments. Check the Branch and click Deploy.

Turn on auto-deploy

To deploy every push to the branch automatically, click the Settings tab, then click Update auto-deploy in the Auto-deploy section. Turn on Auto-deploy and click Update auto-deploy. See Deployments.

When the deployment’s status changes to Deployed on the Deployments tab, click the domain under the application’s name, for example storefront-x7k2m.sevalla.app. The Astro starter page opens, rendered by the server. From a terminal:

curl -s https://storefront-x7k2m.sevalla.app/ | grep -o '<title>[^<]*</title>'

<title>Astro Basics</title>

With the API, Get deployment (getDeploymentV3) returns the deployment’s status, success once it’s deployed, and Get application deployment logs (getApplicationDeploymentLogsV3) returns its build log, which ends with Web has been deployed successfully. See Deploy the application with the API. If the deployment fails, read its build log, then see Troubleshoot Ingot builds. A build log that shows Astro builds for Vercel with @astrojs/vercel, which no server in the image can run (or Netlify or Cloudflare Workers) means the project still has another platform’s adapter: remove it and add the Node.js adapter with npx astro add node. Astro’s hashed assets under /_astro/ are safe to cache for a long time: turn on the CDN on the application’s Networking tab to serve them from Cloudflare. See CDN and edge caching.

Deploy with a Dockerfile

Ingot needs no Dockerfile. Write one when you want full control of the image: the base image, the system packages and every layer. This one runs the server that the Node.js adapter builds, as set up in Render pages on demand. Add a Dockerfile and a .dockerignore to the root of the repository:

Dockerfile

FROM node:24-trixie AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build && npm prune --omit=dev

FROM node:24-trixie-slim
# hadolint ignore=DL3008
RUN apt-get update \
    && apt-get install -y --no-install-recommends tini \
    && rm -rf /var/lib/apt/lists/*
WORKDIR /app
ENV NODE_ENV=production HOST=0.0.0.0 PORT=8080
COPY --from=build /app/node_modules ./node_modules
COPY --from=build /app/dist ./dist
USER 1000:1000
EXPOSE 8080
ENTRYPOINT ["tini", "--"]
CMD ["node", "dist/server/entry.mjs"]

Line or choice	Why
`node:24-trixie`, then `node:24-trixie-slim`	Node.js 24, the line that `engines.node` pins, on Debian 13. The build stage has the compilers that native modules need; the slim final image leaves them out. A line tag picks up Node.js and Debian security fixes at every build, which a digest would stop.
Two stages	The build stage installs every dependency, runs `astro build`, then removes any `devDependencies` with `npm prune --omit=dev`. The final image gets `dist` and the production dependencies, which the server in `dist/server/entry.mjs` imports.
The lock file before the source	`npm ci` installs exactly what `package-lock.json` lists, and the build cache reuses that layer until the lock file changes, so a code change doesn’t reinstall the dependencies.
`USER 1000:1000`	The server runs as the image’s `node` user, not as root. Root owns the copied files, so the server can’t change its own code.
`tini`	The Node.js adapter doesn’t handle `SIGTERM`, and Node.js ignores it as the container’s main process, so an instance would wait to be killed. `tini` runs as the main process and passes the signal on, so the server stops as soon as Sevalla stops the instance. It comes from Debian’s packages without a pinned version, so each build gets its security fixes; `# hadolint ignore=DL3008` tells the hadolint linter that this is on purpose.
`HOST=0.0.0.0`	Without it, the adapter listens on `localhost` only, which Sevalla can’t reach.
`PORT=8080`, `EXPOSE 8080`	The adapter listens on `PORT`. Sevalla sets it to the web process’s port; `8080` is the default when you run the image yourself.

.dockerignore

.git
.astro
dist
node_modules
.env*
*.log
Dockerfile
.dockerignore

The .dockerignore keeps local builds, installed packages and local environment files out of the image, so it builds from the committed source only. Commit and push both files. Ingot doesn’t use the Dockerfile and adds your .dockerignore patterns to its own, so you can keep both files in a repository that builds with Ingot. Then switch the application to the Dockerfile build strategy:

Choose the Dockerfile build strategy

On the application’s Settings tab, in the Build strategy section, click Update build strategy. Click Dockerfile, keep the Dockerfile path Dockerfile and the Docker context ., then click Update build strategy.

Deploy

Click the Overview tab, then click Deploy now under Recent deployments. Check the Branch and click Deploy.

The deployment’s build log shows 📦 Building and pushing docker image using Dockerfile... instead of Ingot’s build plan, and its Dockerfile tab shows your file. When the status changes to Deployed, the application’s domain opens the Astro starter page, rendered by the server, and curl -s https://storefront-x7k2m.sevalla.app/ | grep -o '<title>[^<]*</title>' prints <title>Astro Basics</title> again. See Dockerfile for build arguments and private base images, and Build from the Dockerfile with the API to switch the build strategy with the API.

Add a custom domain

To serve the site from your own domain, such as shop.example.com, add the domain on the static site’s Domains tab and create the DNS records that Sevalla shows. Applications have a Domains tab too, but custom domains need a web process larger than H1. See Custom domains.

Deploy with the API

These calls make the same deployments as Deploy to Sevalla and Render pages on demand, in an order that a script or an AI agent runs as it is. Each step names the Sevalla API operation, then the CLI command and the MCP server tool that do the same. You need:

An API key with the Company developer role, or the STATIC_SITE:CREATE, STATIC_SITE:READ and STATIC_SITE:UPDATE permissions for the static site and APP:CREATE, APP:READ and APP:UPDATE for the application, in the SEVALLA_API_KEY environment variable. The CLI reads the key from SEVALLA_API_TOKEN.
The repository on a Git provider that’s connected to your Sevalla account. See Git providers. Creating the static site or the application checks it: when Sevalla can’t read the repository, the call returns 400 with Cannot access repository https://github.com/acme/storefront: Repository not found or you don't have access., followed by where to grant access.
curl and jq.

Deploy the static site with the API

Create the static site

Create static site (createStaticSiteV3) creates the static site with the build settings from Deploy to Sevalla. "node_version":"lts" is Latest LTS. Unlike the dashboard, the API turns on auto-deploy only when the body asks for it, and it doesn’t start a deployment:

SITE_ID=$(curl -s -X POST https://api.sevalla.com/v3/static-sites \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"storefront","source":"privateGit","git_type":"github","repo_url":"https://github.com/acme/storefront","default_branch":"main","auto_deploy":true,"build_command":"npm run build","node_version":"lts","published_directory":"dist"}' \
  | jq -r .id)

CLI:

sevalla static-sites create --name storefront --source privateGit --git-type github --repository https://github.com/acme/storefront --branch main --build-command "npm run build" --node-version lts --publish-directory dist

, which leaves auto-deploy off. MCP: create_static_site with the same fields.

Deploy

Deploy static site (deployStaticSiteV3) builds and publishes the latest commit on the branch:

DEPLOYMENT_ID=$(curl -s -X POST https://api.sevalla.com/v3/static-sites/$SITE_ID/deployments \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq -r .id)

CLI: sevalla static-sites deployments trigger $SITE_ID. MCP: trigger_deployment with service_type set to static_site.

Wait for the deployment

Get static site deployment (getStaticSiteDeploymentV3) returns the deployment’s status: waiting and inProgress while it runs, then success or failed. Poll it every 15 seconds, for up to 30 minutes, until the status is final:

for i in $(seq 1 120); do
  STATUS=$(curl -s "https://api.sevalla.com/v3/static-sites/$SITE_ID/deployments/$DEPLOYMENT_ID" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.status // empty')
  case $STATUS in success|failed|cancelled|skipped) break ;; esac
  sleep 15
done
echo "$STATUS"

CLI: sevalla static-sites deployments get $DEPLOYMENT_ID --site-id $SITE_ID. MCP: get_deployment with service_type set to static_site.

Read the build log

Get static site deployment logs (getStaticSiteDeploymentLogsV3) returns the build log, oldest line first: the build settings, the install, the build and the upload, which ends with Static site has been deployed successfully. When the status is failed, the last lines say why. Without limit, the call returns the latest 1,000 lines, so a longer log loses its start; 5000 is the most it allows.

curl -s "https://api.sevalla.com/v3/static-sites/$SITE_ID/deployments/$DEPLOYMENT_ID/logs?limit=5000" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.[].message'

CLI: sevalla static-sites deployments logs $DEPLOYMENT_ID --site-id $SITE_ID. MCP: get_deployment_logs with service_type set to static_site.

Check the site

Get static site (getStaticSiteV3) returns the site’s domain in hostname. Request the home page from it:

HOST=$(curl -s https://api.sevalla.com/v3/static-sites/$SITE_ID \
  -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r .hostname)
curl -s https://$HOST/ | grep -o '<title>[^<]*</title>'

<title>Astro Basics</title>

CLI: sevalla static-sites get $SITE_ID. MCP: get_static_site.

Deploy the application with the API

These steps deploy the project from Render pages on demand as an application.

Choose the location

List clusters (listClustersV3) returns the locations your company can use, each with its id, its display_name and its region ID in location (see Locations). Keep the ID of the one you want, here Frankfurt, Germany:

CLUSTER_ID=$(curl -s https://api.sevalla.com/v3/resources/clusters \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.[] | select(.location == "eu-frankfurt-1") | .id')

CLI: sevalla resources clusters. MCP: get_platform_options.

Find the H1 size

List process resource types (listProcessResourceTypesV3) returns the sizes by name, in lowercase:

H1_ID=$(curl -s https://api.sevalla.com/v3/resources/process-resource-types \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.[] | select(.name == "h1") | .id')

CLI: sevalla resources process-types. MCP: get_platform_options.

Create the application

Create application (createApplicationV3) creates the application with a web process and auto-deploy off. It builds with Ingot (build_type is ingot) and isn’t deployed yet:

APP_ID=$(curl -s -X POST https://api.sevalla.com/v3/applications \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"storefront","cluster_id":"'"$CLUSTER_ID"'","source":"privateGit","git_type":"github","repo_url":"https://github.com/acme/storefront","default_branch":"main"}' \
  | jq -r .id)

CLI:

sevalla apps create --name storefront --cluster $CLUSTER_ID --source privateGit --git-type github --repository https://github.com/acme/storefront --branch main

. MCP: create_application with deploy set to false, because it deploys by default.

Find the web process

List processes (listProcessesV3) returns the web process that the application was created with:

WEB_ID=$(curl -s https://api.sevalla.com/v3/applications/$APP_ID/processes \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.data[] | select(.type == "web") | .id')

CLI: sevalla apps processes list --app-id $APP_ID. MCP: get_application.

Set the size

The API creates the web process at S1, where the dashboard’s default is H1. Update process (updateProcessV3) sets H1:

curl -s -X PATCH https://api.sevalla.com/v3/applications/$APP_ID/processes/$WEB_ID \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"resource_type_id":"'"$H1_ID"'"}' \
  | jq -c '{resource_type_name, cpu_limit, memory_limit}'

{"resource_type_name":"h1","cpu_limit":300,"memory_limit":300}

CLI: sevalla apps processes update $WEB_ID --app-id $APP_ID --resource-type $H1_ID. MCP: scale_process with size_id and apply_now set to false.

Turn on auto-deploy

Update application (updateApplicationV3) turns on automatic deployments for every push to the branch:

curl -s -X PATCH https://api.sevalla.com/v3/applications/$APP_ID \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"auto_deploy":true}' | jq .auto_deploy

CLI: sevalla apps update $APP_ID --data '{"auto_deploy":true}'. MCP: sevalla_api_update with updateApplicationV3.

Deploy

Trigger deployment (triggerDeploymentV3) deploys the latest commit on the application’s branch:

DEPLOYMENT_ID=$(curl -s -X POST https://api.sevalla.com/v3/applications/$APP_ID/deployments \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}' | jq -r .id)

CLI: sevalla apps deployments trigger $APP_ID. MCP: trigger_deployment.

Wait for the deployment

Get deployment (getDeploymentV3) returns the deployment’s status: waiting and inProgress while it runs, then success or failed. Poll it every 15 seconds, for up to 30 minutes, until the status is final:

for i in $(seq 1 120); do
  STATUS=$(curl -s "https://api.sevalla.com/v3/applications/$APP_ID/deployments/$DEPLOYMENT_ID" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.status // empty')
  case $STATUS in success|failed|cancelled|skipped) break ;; esac
  sleep 15
done
echo "$STATUS"

CLI: sevalla apps deployments get $DEPLOYMENT_ID --app-id $APP_ID. MCP: get_deployment.

Read the build log

Get application deployment logs (getApplicationDeploymentLogsV3) returns the build log, oldest line first: the build plan from Render pages on demand, the build and the rollout, which ends with Web has been deployed successfully. When the status is failed, the last lines say why. Without limit, the call returns the latest 1,000 lines, so a longer log loses its start; 5000 is the most it allows.

curl -s "https://api.sevalla.com/v3/applications/$APP_ID/deployments/$DEPLOYMENT_ID/logs?limit=5000" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.[].message'

CLI: sevalla apps deployments logs $DEPLOYMENT_ID --app-id $APP_ID. MCP: get_deployment_logs.

Check the application

List application domains (listApplicationDomainsV3) returns the application’s domain. Request the home page from it:

HOST=$(curl -s https://api.sevalla.com/v3/applications/$APP_ID/domains \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.data[] | select(.is_primary) | .name')
curl -s https://$HOST/ | grep -o '<title>[^<]*</title>'

<title>Astro Basics</title>

CLI: sevalla apps domains list --app-id $APP_ID. MCP: get_application.

Build from the Dockerfile with the API

After you push the Dockerfile from Deploy with a Dockerfile, Update application (updateApplicationV3) switches the application’s build strategy. Then repeat the application’s Deploy, Wait for the deployment and Check the application steps:

curl -s -X PATCH https://api.sevalla.com/v3/applications/$APP_ID \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"build_type":"dockerfile","dockerfile_path":"Dockerfile","docker_context":"."}' \
  | jq -c '{build_type, dockerfile_path, docker_context}'

{"build_type":"dockerfile","dockerfile_path":"Dockerfile","docker_context":"."}

CLI: sevalla apps update $APP_ID --data '{"build_type":"dockerfile","dockerfile_path":"Dockerfile","docker_context":"."}'. MCP: sevalla_api_update with updateApplicationV3.

Get started

Migrate

AI

JavaScript

Python

PHP

Ruby

Go

Rust

Java, Kotlin and Scala

.NET

Elixir

Gleam

Swift

Dart

Static site generators

At a glance

Environment variables

Before you begin

Create the project

Prepare the project for Sevalla

Deploy to Sevalla

Verify the deployment

Render pages on demand

Deploy with a Dockerfile

Add a custom domain

Deploy with the API

Deploy the static site with the API

Deploy the application with the API

Build from the Dockerfile with the API

​At a glance

​Environment variables

​Before you begin

​Create the project

​Prepare the project for Sevalla

​Deploy to Sevalla

​Verify the deployment

​Render pages on demand

​Deploy with a Dockerfile

​Add a custom domain

​Deploy with the API

​Deploy the static site with the API

​Deploy the application with the API

​Build from the Dockerfile with the API

At a glance

Environment variables

Before you begin

Create the project

Prepare the project for Sevalla

Deploy to Sevalla

Verify the deployment

Render pages on demand

Deploy with a Dockerfile

Add a custom domain

Deploy with the API

Deploy the static site with the API

Deploy the application with the API

Build from the Dockerfile with the API