Deploy an EmDash site

EmDash is a CMS built on Astro. It runs on Sevalla as an application that Ingot builds with no configuration, keeps content, users and sessions in a Sevalla PostgreSQL database, stores uploaded media in object storage, and serves pages from Cloudflare with edge caching that the application purges through the Sevalla API when an editor publishes. This guide deploys Sevalla’s EmDash template, which has all of this set up.

At a glance


Source	A Git repository with a copy of the EmDash template for Sevalla
Build	Ingot (Node.js 24, npm), or the Dockerfile
Start command	`node ./server.mjs`, from `scripts.start` in `package.json`
Port	The `PORT` environment variable, `8080` by default
Processes	Web process; optional `Migrate` job (`npm run migrate`, Before deployment)
Services	PostgreSQL 16 or newer over an internal connection; an object storage bucket with public access and a CORS rule
Disk	None
Health check	`GET /healthz` returns `200` (liveness probe); `GET /healthz?db=1` returns `200` when PostgreSQL answers (readiness probe)
Size	H1 for the web process and the job

Environment variables

The template reads every variable when the server starts, so none has to be available during the build.

Variable	Required	Available during	Secret	Value
`DB_URL`	Yes	Runtime	Yes	`postgres://<user>:<password>@<host>:<port>/<database>`, added by the internal connection
`DATABASE_URL`	No	Runtime	Yes	Read before `DB_URL` when it’s set; the MCP server’s `create_database` stores the URL here. `postgres://` and `postgresql://` both work
`DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`	No	Runtime	`DB_PASSWORD`	Added by the internal connection with `DB_URL`; the template doesn’t read them
`EMDASH_SITE_URL`	Yes	Runtime	No	The application’s address, such as `https://storefront-x7k2m.sevalla.app`
`EMDASH_ENCRYPTION_KEY`	Yes	Runtime	Yes	Generate with `npx emdash secrets generate`
`S3_ENDPOINT`	Yes	Runtime	No	The bucket’s Endpoint
`S3_BUCKET`	Yes	Runtime	No	The bucket’s Bucket name
`S3_ACCESS_KEY_ID`	Yes	Runtime	Yes	The bucket’s Access key
`S3_SECRET_ACCESS_KEY`	Yes	Runtime	Yes	The bucket’s Secret key
`S3_REGION`	Yes	Runtime	No	`auto`
`S3_PUBLIC_URL`	No	Runtime	No	`https://` and the bucket’s Public domain; without it, media is served through the application
`SEVALLA_APP_ID`	No	Runtime	No	The application’s ID
`SEVALLA_API_KEY`	No	Runtime	Yes	An API key with Update for this application; without it and `SEVALLA_APP_ID`, the edge cache isn’t purged on publish
`PORT`	No	Runtime	No	Set by Sevalla to the 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 22.16 or later on your computer, to generate the encryption key.

Use the example repository

The EmDash template for Sevalla is EmDash’s blog template with the hosting layer adapted to Sevalla:

Part	What the template does
Database	Uses PostgreSQL instead of SQLite, reads the connection URL when the server starts, and searches posts with PostgreSQL full-text search.
Sessions	Stores Astro sessions in PostgreSQL, so editors stay signed in across deployments and instances.
Media	Uploads to object storage with presigned URLs and serves files from the bucket’s public domain.
Caching	Sends `Cache-Control` headers for public pages and purges the application’s edge cache after every content change.
Server	Starts Astro’s Node server through `server.mjs`, which listens on `PORT`. The build needs no environment variables.

Create an empty repository on your Git provider, such as acme/storefront, then copy the template into it and generate the key that encrypts EmDash’s plugin secrets:

git clone https://github.com/sevalla-templates/emdash-template.git storefront
cd storefront
git remote set-url origin https://github.com/acme/storefront.git
git push -u origin main
npm install
npx emdash secrets generate

Keep the generated key in a password manager: you add it as EMDASH_ENCRYPTION_KEY in the deployment steps, and EmDash can’t read its stored secrets without it.

Prepare the project for Sevalla

The template needs no code changes. Its parts depend on four Sevalla services, which you create in Deploy to Sevalla in the same location, because an internal connection only works within one location:

A PostgreSQL database. The database user that Sevalla creates owns the database, which EmDash needs because it creates and alters its own tables.
The application. Ingot, the default build strategy, detects Astro with the Node adapter and starts the server with the start script, node ./server.mjs. The template also has a Dockerfile, which Ingot doesn’t use: it generates its own, and adds the patterns in the template’s .dockerignore to it. To build from a Dockerfile instead, see Deploy with a Dockerfile.
An object storage bucket with public access and a CORS rule, so the admin panel can upload from the browser.
An API key that can update the application, used to purge the edge cache.

Deploy to Sevalla

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

Create the database

In the sidebar, click Databases, then click Create database. Under Database, choose PostgreSQL and version 16 or newer. Enter orders-db as the Display name, choose a Data center and a Size, then click Create database. See Create a database for every field.

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 the same Data center as the database. 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.

Connect the database

Click the Networking tab. Under Connected services, click Add internal connection. Choose orders-db as the Service, turn on Add environment variables to the application, and click Add internal connection. The template reads the DB_URL variable that Sevalla adds. See Connect an application.

Create the bucket

In the sidebar, click Object storage, then click Create object storage. Enter a Name, choose the Location closest to the application, then click Create object storage. See Create a bucket.

Open the bucket to the admin panel

On the bucket’s Settings tab, under Public access, click Enable public access and confirm. Then, under CORS policy, click Create rule. Select PUT, GET and HEAD under Allowed methods, enter the application’s address, such as https://storefront-x7k2m.sevalla.app, under Allowed origins and content-type under Allowed headers, then click Create CORS rule. See Bucket settings.

Create an API key

In the sidebar, under Tools, click API keys, then click Create API key. Enter a Name, such as storefront-cache-purge, and click Custom capabilities. Under Capabilities, select Update in the App row. Under Resource scope, choose Specific app resources and select the application. Click Create API key and copy the key. Purging the edge cache needs the APP:UPDATE permission, and this key has it for this application only. See API keys.

Add the environment variables

On the application’s Environment variables tab, click Add environment variables. Add these variables and click Add environment variables:

Variable	Value
`EMDASH_SITE_URL`	The application’s address, such as `https://storefront-x7k2m.sevalla.app`. Set it before you run the setup wizard: passkeys only work on the address they were registered on.
`EMDASH_ENCRYPTION_KEY`	The key that `npx emdash secrets generate` printed.
`S3_ENDPOINT`	The bucket’s Endpoint, from its Settings tab.
`S3_BUCKET`	The bucket’s Bucket name, not its display name.
`S3_ACCESS_KEY_ID`	The bucket’s Access key.
`S3_SECRET_ACCESS_KEY`	The bucket’s Secret key.
`S3_REGION`	`auto`
`S3_PUBLIC_URL`	`https://` followed by the bucket’s Public domain. Without it, media is served through the application.
`SEVALLA_APP_ID`	The application’s ID, from its Settings tab.
`SEVALLA_API_KEY`	The API key you created. Without it and `SEVALLA_APP_ID`, pages update only when their cache time runs out, 1 hour by default.

The template reads them when the server starts, so they don’t need to be available during the build.

Turn on the CDN and edge caching

On the application’s Networking tab, under CDN & Edge caching, click Update settings. Turn on CDN and Edge caching, then click Done. See CDN and edge caching.

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.

See Connect with the S3 API for where each bucket value comes from.

Verify the deployment

On the Deployments tab, click the deployment. Its Build log shows Ingot’s build plan: Node.js 24, which satisfies the template’s engines.node, npm from package-lock.json, and the start command from the start script.

Build log

╭─ ■ Astro (Node adapter) · Node.js 24 ─────────────────────────────────────────────╮
│ Node.js          24                              package.json engines ">=22.16.0" │
│ Package manager  npm                             package-lock.json                │
│ Framework        Astro (Node adapter)            package.json                     │
│ Start            node ./server.mjs               package.json scripts.start       │
│ DevDependencies  removed after the build                                          │
│ Ignored          20 patterns from .dockerignore  .dockerignore                    │
├─ Image ───────────────────────────────────────────────────────────────────────────┤
│ Build            node:24-trixie                                                   │
│ Runtime          node:24-trixie-slim                                              │
│ User             1000:1000                                                        │
│ Init             tini                                                             │
│ Port             $PORT, default 8080                                              │
╰──────────────────────────────────────────────────────────────────── Ingot v0.5.0 ─╯

! EmDash encrypts plugin secrets with EMDASH_ENCRYPTION_KEY, which npm create emdash writes to .env, outside the repository: set it at runtime, made with npx emdash secrets generate

Ingot prints the ! warning for every EmDash site. The Add the environment variables step in Deploy to Sevalla sets EMDASH_ENCRYPTION_KEY, so there’s nothing to do.

Wait for the deployment’s status to change to Deployed. The application’s status next to its name changes to Running.

Check from a terminal that the server runs and reaches PostgreSQL:

curl -s "https://storefront-x7k2m.sevalla.app/healthz?db=1"

{"status":"ok","db":"ok"}

Open the application’s address followed by /_emdash/admin, for example https://storefront-x7k2m.sevalla.app/_emdash/admin. The setup wizard creates the site, can load the demo content, and registers your admin passkey. EmDash applies its database migrations on the first request.
Publish a post, then open the site’s home page. The post shows without waiting for the cached page to expire, because publishing purges the edge cache: the application’s runtime logs show [sevalla] Edge cache purge requested a few seconds after you publish.

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. Get application runtime logs (getApplicationRuntimeLogsV3) with search finds the purge:

curl -s "https://api.sevalla.com/v3/applications/$APP_ID/runtime-logs?search=Edge%20cache%20purge" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.[].message'

[sevalla] Edge cache purge requested

See Deploy with the API. If the deployment fails, open it on the Deployments tab and read its build log, then see Troubleshoot builds and deployments. If media uploads fail in the admin panel, check the bucket’s CORS rule. For the template’s own messages in the runtime logs:

Log message	Cause	Fix
`DATABASE_URL is not set`	The internal connection was added without its variables, so the application has no `DB_URL`	Disconnect the database, add the internal connection again with Add environment variables to the application turned on, then deploy.
`Content changed but SEVALLA_APP_ID / SEVALLA_API_KEY are not set, so the edge cache was not purged.`	One of the two variables is missing	Add both, then deploy.
`Edge cache purge failed: HTTP` followed by a status code	The Sevalla API refused the purge	Check that `SEVALLA_APP_ID` is this application’s ID and that the API key has Update for it, then deploy.

Deploy changes

With Auto-deploy on, every push to the branch starts a deployment; otherwise, click Deploy now for each change. Each deployment builds the image, then replaces the web process’s instances. See Deployments.

Add health checks

The template answers /healthz when the server runs and /healthz?db=1 when it can also reach PostgreSQL. Use them as the web process’s probes, so that Sevalla restarts an instance that stops responding and sends traffic only to instances that reach the database:

Open the web process

On the Processes tab, open the web process’s menu and click Update process.

Turn on the probes

Under Health checks, turn on Liveness probe with the Path /healthz, and Readiness probe with the Path /healthz?db=1. Click Update process. The probes apply at the next deployment.

See Processes for the other probe settings.

Run migrations before each deployment

Without a job, the first request after a deployment applies EmDash’s pending migrations. To apply them once, before new instances get traffic, add a job:

Create the job

On the Processes tab, click Create process and choose Job.

Set its command

Enter Migrate as the Name and npm run migrate as the Custom start command. Keep the Start policy at Before deployment, then click Create process.

The template’s migrate script runs emdash migrate without prompts. It’s the job Ingot recommends for the template: Ingot finds migrate in package.json and lists npm run migrate among the processes it recommends, but doesn’t create it. If the job fails, the deployment fails and nothing changes for visitors. In the next deployment’s build log, the job runs after the build, as ⏩ Running Migrate (timeout: 600s)..., and ends with ✅ Migrate has been successful before the web process rolls out.

Deploy with a Dockerfile

Ingot needs no Dockerfile. Write your own when you want full control of the image: the base image, the system packages and every layer. Replace the template’s Dockerfile with this one:

Dockerfile

FROM node:24-trixie-slim AS build
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:24-trixie-slim
WORKDIR /app
ENV NODE_ENV=production PORT=8080
COPY package.json package-lock.json ./
RUN npm ci --omit=dev && npm cache clean --force
COPY --from=build /app/dist ./dist
COPY --from=build /app/.emdash ./.emdash
COPY scripts ./scripts
COPY server.mjs ./
USER 1000:1000
EXPOSE 8080
CMD ["node", "server.mjs"]

Line or choice	Why
Two stages	The `build` stage installs every dependency and runs `astro build`, which writes the server to `dist/` and EmDash’s migration list to `.emdash/`. The final image gets those, the production dependencies, `server.mjs` and the `scripts/` that the `migrate` script runs, so the migration job works with this image too.
`node:24-trixie-slim`	The official Node.js 24 image on Debian 13, the line Ingot picks for the template’s `engines.node`. The tag follows Node.js 24’s patch releases, so each build gets its security fixes; a digest would stay on one release.
`package.json` and `package-lock.json` first	`npm ci` installs the exact versions in the lock file, and `--omit=dev` leaves out devDependencies in the final image. Copying the two files before the code lets Docker reuse the installed dependencies when only the code changes.
`USER 1000:1000`	The server runs as the image’s unprivileged `node` user. The files stay owned by root, so the server can read them but not change them. EmDash keeps its content in PostgreSQL and its media in the bucket, so it writes nothing to `/app`.
No init process	`server.mjs` handles `SIGTERM` itself: it finishes the requests in progress, then exits.
`PORT=8080` and `EXPOSE 8080`	`server.mjs` listens on `PORT`, which Sevalla sets at runtime, on `0.0.0.0`. The image’s default matches Sevalla’s, for running it on your computer.

The build needs no environment variables, and the image holds no secrets: the application reads its variables when the server starts. Keep the template’s .dockerignore, which keeps node_modules, dist, .git, local .env files and SQLite databases out of the build. Commit and push the Dockerfile. Ingot doesn’t use it, so you can keep it 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 Update build strategy sheet with Dockerfile selected, the Dockerfile path, the Docker context and the Docker registry credential

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 Dockerfile. When the deployment is Deployed, curl -s "https://storefront-x7k2m.sevalla.app/healthz?db=1" prints {"status":"ok","db":"ok"}, and publishing a post purges the edge cache as before. See Dockerfile for build arguments and private base images, and Deploy with the API to switch the build strategy with the API.

Add a custom domain

Custom domains need a web process larger than H1, so scale the web process first. After you add the domain on the Domains tab (see Custom domains), change EMDASH_SITE_URL to the new address, add the new address to the bucket’s CORS rule, and deploy again. CORS rules can’t be updated: delete the rule and create a new one with both origins.

Set the custom domain in EMDASH_SITE_URL before you run the setup wizard: passkeys only work on the hostname they were created on. After a change, passkeys registered on the old address, such as storefront-x7k2m.sevalla.app, stop working, and the template has no other way to sign in. EmDash’s magic links need an email provider and its OAuth sign-in needs a provider in astro.config.mjs, and the template configures neither.

Scale the application

The template keeps no state in the instance, so you can run more than one instance or turn on autoscaling. Keep at least one instance running: EmDash’s scheduler for scheduled posts runs inside the web process. See Scaling.

Deploy with the API

These calls make the same deployment as Deploy to Sevalla, Add health checks and Run migrations before each deployment, 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 in the SEVALLA_API_KEY environment variable: the steps create a database, a bucket and an API key as well as the application. The CLI reads the key from SEVALLA_API_TOKEN.
The repository from Use the example repository on a Git provider that’s connected to your Sevalla account. See Git providers. Creating 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.
The encryption key in EMDASH_ENCRYPTION_KEY. npx emdash secrets generate prints only the key to standard output, so in the project folder, after npm install, run EMDASH_ENCRYPTION_KEY=$(npx emdash secrets generate).
curl, jq and openssl.

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). The database and the application must be in the same one. 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 database size

List database resource types (listDatabaseResourceTypesV3) returns the database sizes by name. db1, the smallest, is enough for a blog:

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

CLI: sevalla resources db-types. MCP: get_platform_options with kind set to database.

Create the database

Create database (createDatabaseV3) creates PostgreSQL 18 with a database and a user named storefront, which owns the database. The API doesn’t return the password later, so generate it first and keep it in DB_PASSWORD. A hex password needs no escaping in DB_URL:

DB_PASSWORD=$(openssl rand -hex 24)
DB_ID=$(curl -s -X POST https://api.sevalla.com/v3/databases \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"orders-db","type":"postgresql","version":"18","cluster_id":"'"$CLUSTER_ID"'","resource_type_id":"'"$DB_SIZE_ID"'","db_name":"storefront","db_user":"storefront","db_password":"'"$DB_PASSWORD"'"}' \
  | jq -r .id)

CLI:

sevalla databases create --name orders-db --type postgresql --db-version 18 --cluster $CLUSTER_ID --resource-type $DB_SIZE_ID --db-name storefront --db-user storefront --db-password $DB_PASSWORD

. MCP: create_database, which generates the password itself and never returns it. Given connect_to_application_id once the application exists, it also connects the database and stores a postgresql:// URL in DATABASE_URL, which the template reads before DB_URL: you then skip Connect the database and the DB_ variables.

Find the H1 size

List process resource types (listProcessResourceTypesV3) returns the process 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 and the health checks

The API creates the web process at S1, where the dashboard’s default is H1. Update process (updateProcessV3) sets H1 and adds the probes from Add health checks, with the dashboard’s default timings. Send timeoutSeconds: a probe without it gets 120 seconds, where the dashboard sets 1.

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"'","liveness_probe":{"httpGet":{"path":"/healthz","port":8080,"scheme":"HTTP"},"initialDelaySeconds":0,"periodSeconds":10,"timeoutSeconds":1,"successThreshold":1,"failureThreshold":3},"readiness_probe":{"httpGet":{"path":"/healthz?db=1","port":8080,"scheme":"HTTP"},"initialDelaySeconds":0,"periodSeconds":10,"timeoutSeconds":1,"successThreshold":1,"failureThreshold":3}}' \
  | jq -c '{resource_type_name, liveness: .liveness_probe.httpGet.path, readiness: .readiness_probe.httpGet.path}'

{"resource_type_name":"h1","liveness":"/healthz","readiness":"/healthz?db=1"}

CLI: sevalla apps processes update $WEB_ID --app-id $APP_ID --resource-type $H1_ID sets the size; the CLI can’t set probes. MCP: scale_process with size_id and apply_now set to false for the size, and sevalla_api_update with updateProcessV3 and the same body for the probes.

Create the migration job

Create process (createProcessV3) adds the Migrate job from Run migrations before each deployment. A job needs a size, a scaling strategy and a start policy:

JOB_ID=$(curl -s -X POST https://api.sevalla.com/v3/applications/$APP_ID/processes \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"Migrate","type":"job","entrypoint":"npm run migrate","job_start_policy":"beforeDeployment","resource_type_id":"'"$H1_ID"'","scaling_strategy":{"type":"manual","config":{"instanceCount":1}}}' \
  | jq -r .id)

CLI:

sevalla apps processes create $APP_ID --name Migrate --type job --command "npm run migrate" --job-start-policy beforeDeployment --resource-type $H1_ID

. MCP: sevalla_api_create with createProcessV3 and the same body.

Wait for the database

Get database (getDatabaseV3) returns the database’s status, creating until it’s ready, and its internal hostname and port. Poll it every 15 seconds, for up to 30 minutes, until the status is ready or error, then keep the connection values:

for i in $(seq 1 120); do
  DB=$(curl -s "https://api.sevalla.com/v3/databases/$DB_ID" \
    -H "Authorization: Bearer $SEVALLA_API_KEY")
  STATUS=$(jq -r '.status // empty' <<<"$DB")
  case $STATUS in ready|error) break ;; esac
  sleep 15
done
echo "$STATUS"
DB_HOST=$(jq -r .internal_hostname <<<"$DB")
DB_PORT=$(jq -r .internal_port <<<"$DB")
DB_DATABASE=$(jq -r .db_name <<<"$DB")
DB_USERNAME=$(jq -r .db_user <<<"$DB")

CLI: sevalla databases get $DB_ID. MCP: get_database.

Connect the database

Create internal connection (createApplicationInternalConnectionV3) connects the application to the database. Unlike the dashboard, it doesn’t add environment variables: the Add the environment variables step adds them.

curl -s -X POST https://api.sevalla.com/v3/applications/$APP_ID/internal-connections \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_type":"database","target_id":"'"$DB_ID"'"}' | jq -c 'keys'

["id"]

CLI: sevalla apps internal-connections create $APP_ID --target-type database --target-id $DB_ID. MCP: sevalla_api_create with createApplicationInternalConnectionV3.

Find the domain

List application domains (listApplicationDomainsV3) returns the application’s domain, which exists before the first deployment. EMDASH_SITE_URL and the bucket’s CORS rule need 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')

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

Create the bucket

Create object storage bucket (createObjectStorageV3) creates the bucket with public access, near Frankfurt (weur, Western Europe). Its response is the only one that has the bucket’s access key and secret key, so keep the whole response in BUCKET:

BUCKET=$(curl -s -X POST https://api.sevalla.com/v3/object-storage \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"display_name":"storefront-media","location":"weur","public_access":true}')
BUCKET_ID=$(jq -r .id <<<"$BUCKET")

CLI: sevalla object-storage create --name storefront-media --location weur --json, then sevalla object-storage cdn-domain enable $BUCKET_ID for public access. MCP: sevalla_api_create with createObjectStorageV3.

Add the CORS rule

Create CORS policy (createObjectStorageCorsPolicyV3) lets the admin panel upload from the application’s address:

curl -s -X POST https://api.sevalla.com/v3/object-storage/$BUCKET_ID/cors-policies \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"methods":["PUT","GET","HEAD"],"origins":["https://'"$HOST"'"],"headers":["content-type"]}' \
  | jq -r .message

CORS policy created

CLI:

sevalla object-storage cors-policies create $BUCKET_ID --methods PUT,GET,HEAD --origins https://$HOST --headers content-type

. MCP: sevalla_api_create with createObjectStorageCorsPolicyV3.

Create the cache purge key

Create API key (createApiKeyV3) creates the key the application purges its edge cache with: APP:UPDATE for this application only. The response is the only one that has the key’s token:

PURGE_KEY=$(curl -s -X POST https://api.sevalla.com/v3/api-keys \
  -H "Authorization: Bearer $SEVALLA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"storefront-cache-purge","capabilities":[{"permission":"APP:UPDATE","resource_id":"'"$APP_ID"'"}]}' \
  | jq -r .token)

CLI: sevalla api-keys create --name storefront-cache-purge --capabilities APP:UPDATE --json creates the key for every application: the CLI can’t limit a permission to one application. MCP: sevalla_api_create with createApiKeyV3.

Add the environment variables

Create environment variable (createEnvironmentVariableV3) adds one variable per call. The DB_ variables have the names and formats that the dashboard’s internal connection adds; every variable is available at runtime only. SEVALLA_API_KEY in the application is the purge key, not your own key:

add_var() {
  curl -s -X POST https://api.sevalla.com/v3/applications/$APP_ID/env-vars \
    -H "Authorization: Bearer $SEVALLA_API_KEY" \
    -H "Content-Type: application/json" \
    -d "$(jq -nc --arg key "$1" --arg value "$2" '{key: $key, value: $value, is_runtime: true, is_buildtime: false}')" \
    | jq -r .key
}
add_var DB_HOST "$DB_HOST"
add_var DB_PORT "$DB_PORT"
add_var DB_DATABASE "$DB_DATABASE"
add_var DB_USERNAME "$DB_USERNAME"
add_var DB_PASSWORD "$DB_PASSWORD"
add_var DB_URL "postgres://$DB_USERNAME:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_DATABASE"
add_var EMDASH_SITE_URL "https://$HOST"
add_var EMDASH_ENCRYPTION_KEY "$EMDASH_ENCRYPTION_KEY"
add_var S3_ENDPOINT "$(jq -r .endpoint <<<"$BUCKET")"
add_var S3_BUCKET "$(jq -r .bucket_name <<<"$BUCKET")"
add_var S3_ACCESS_KEY_ID "$(jq -r .access_key <<<"$BUCKET")"
add_var S3_SECRET_ACCESS_KEY "$(jq -r .secret_key <<<"$BUCKET")"
add_var S3_REGION auto
add_var S3_PUBLIC_URL "https://$(jq -r .domain <<<"$BUCKET")"
add_var SEVALLA_APP_ID "$APP_ID"
add_var SEVALLA_API_KEY "$PURGE_KEY"

CLI: sevalla apps env-vars create $APP_ID --key DB_URL --value "...", one call per variable; the CLI makes every variable available during the build and at runtime. MCP: set_environment_variables with runtime set to true and buildtime set to false.

Turn on the CDN

Toggle CDN (toggleApplicationCdnV3) switches the CDN on when it’s off, and off when it’s on, then returns the new state. Check that it’s true:

curl -s -X POST https://api.sevalla.com/v3/applications/$APP_ID/cdn/toggle \
  -H "Authorization: Bearer $SEVALLA_API_KEY"

{"is_turned_on":true}

CLI: sevalla apps cdn-toggle $APP_ID. MCP: sevalla_api_create with toggleApplicationCdnV3.

Turn on edge caching

Toggle edge cache (toggleApplicationEdgeCacheV3) works the same way for edge caching:

curl -s -X POST https://api.sevalla.com/v3/applications/$APP_ID/edge-cache/toggle \
  -H "Authorization: Bearer $SEVALLA_API_KEY"

{"is_turned_on":true}

CLI: sevalla apps edge-cache-toggle $APP_ID. MCP: sevalla_api_create with toggleApplicationEdgeCacheV3.

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 Verify the deployment, the build, the Migrate job 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

The readiness probe’s address answers when the server runs and reaches PostgreSQL:

curl -s "https://$HOST/healthz?db=1"

{"status":"ok","db":"ok"}

Then open https://$HOST/_emdash/admin in a browser to run the setup wizard, as in Verify the deployment: registering a passkey needs one.

Build from the Dockerfile with the API

After you push the Dockerfile from Deploy with a Dockerfile, Update application (updateApplicationV3) switches the build strategy. Then repeat the 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

Use the example repository

Prepare the project for Sevalla

Deploy to Sevalla

Verify the deployment

Deploy changes

Add health checks

Run migrations before each deployment

Deploy with a Dockerfile

Add a custom domain

Scale the application

Deploy with the API

Build from the Dockerfile with the API

​At a glance

​Environment variables

​Before you begin

​Use the example repository

​Prepare the project for Sevalla

​Deploy to Sevalla

​Verify the deployment

​Deploy changes

​Add health checks

​Run migrations before each deployment

​Deploy with a Dockerfile

​Add a custom domain

​Scale the application

​Deploy with the API

​Build from the Dockerfile with the API

At a glance

Environment variables

Before you begin

Use the example repository

Prepare the project for Sevalla

Deploy to Sevalla

Verify the deployment

Deploy changes

Add health checks

Run migrations before each deployment

Deploy with a Dockerfile

Add a custom domain

Scale the application

Deploy with the API

Build from the Dockerfile with the API