Deploy a Dart Frog application

A Dart Frog server runs on Sevalla as an application built from a Dockerfile in your Git repository: the official dart image generates the server with dart_frog build, compiles it ahead of time (AOT) into one native executable, and the web process runs that executable on Debian slim. Ingot, Sevalla’s default builder, has no Dart provider, so you choose the Dockerfile build strategy before the first deployment: with Ingot, the build stops with Ingot couldn't tell what kind of application this is. The server listens on the port that Sevalla sets in the PORT environment variable.

At a glance


Source	A Git repository with a `Dockerfile`
Build	The Dockerfile: `dart:3.13` compiles the server, `debian:trixie-slim` runs it. Ingot has no Dart provider
Start command	`/app/server`, the `CMD` of the Dockerfile
Port	The `PORT` environment variable, `8080` by default
Processes	Web process
Services	None
Disk	None
Health check	None
Size	H1 for the web process

Environment variables

The application needs no environment variables of its own. It reads PORT, which Sevalla sets 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.
The Dart 3.13 SDK on your computer.

Create the project

Install the Dart Frog command-line tool, then create a project named storefront:

dart pub global activate dart_frog_cli 1.2.14
dart_frog create storefront
cd storefront

The project has one route, routes/index.dart, which answers every request to / with Welcome to Dart Frog!. dart_frog create also installs the dependencies, Dart Frog 1.2.6 among them, and writes their versions to pubspec.lock. Run dart_frog dev and open http://localhost:8080 to check it.

Prepare the project for Sevalla

Dart Frog’s .gitignore leaves pubspec.lock out of the repository. Delete the pubspec.lock line from .gitignore, so the lock file is committed and every build installs the versions you tested:

.gitignore

# Files and directories created by pub
.dart_tool/
.packages

Add a custom entry point that stops the server when it receives SIGTERM:

main.dart

import 'dart:io';

import 'package:dart_frog/dart_frog.dart';

Future<HttpServer> run(Handler handler, InternetAddress ip, int port) async {
  final server = await serve(handler, ip, port);
  ProcessSignal.sigterm.watch().first.then((_) async {
    await server.close();
    stdout.writeln('Server stopped');
    exit(0);
  });
  return server;
}

Dart Frog calls run from the server it generates, with the address and the port it listens on. See Shut down gracefully for why the server needs this file.

File	Why Sevalla needs it
`pubspec.yaml` and `pubspec.lock`	The dependencies and their exact versions. The Dockerfile installs them with `dart pub get --enforce-lockfile`, which fails when `pubspec.lock` is missing or doesn’t match `pubspec.yaml`.
`main.dart`	Closes the server on `SIGTERM`, so a deployment replaces an instance at once.
`routes/`	The routes that `dart_frog build` turns into the server
`Dockerfile` and `.dockerignore`	Build the image. See Deploy with a Dockerfile.

The server needs no port configuration: the server that Dart Frog generates reads PORT, which Sevalla sets to the web process’s port (8080 by default), and listens on every IPv4 and IPv6 address.

Deploy with a Dockerfile

Ingot has no Dart provider, so Sevalla builds this application from a Dockerfile that you add to the repository. Add a Dockerfile and a .dockerignore to the root of the project:

Dockerfile

FROM dart:3.13 AS build
RUN dart pub global activate dart_frog_cli 1.2.14
WORKDIR /app
COPY pubspec.yaml pubspec.lock ./
RUN dart pub get --enforce-lockfile
COPY . .
RUN dart pub global run dart_frog_cli:dart_frog build \
  && dart compile exe build/bin/server.dart -o build/bin/server

FROM debian:trixie-slim
COPY --from=build /app/build/bin/server /app/server
USER 1000:1000
EXPOSE 8080
CMD ["/app/server"]

Line or choice	Why
`dart:3.13`	The official Dart image with the Dart 3.13 SDK, on Debian 13. A line tag, not a digest, so each build gets Dart’s 3.13 patch releases and Debian’s security fixes.
`dart_frog_cli 1.2.14`	The same Dart Frog tool you created the project with, pinned, in its own layer that Docker reuses on every build
`pubspec.yaml` and `pubspec.lock` copied before the code	`dart pub get` downloads the packages in a layer that Docker reuses until one of the two files changes, so a code change starts from there
`dart_frog build`, then `dart compile exe`	`dart_frog build` writes the server, with your routes and `main.dart`, to `build/bin/server.dart`. `dart compile exe` compiles it ahead of time into one native executable, which needs no Dart SDK to run and starts in milliseconds.
`debian:trixie-slim`	The executable links to the GNU C library, so it runs on Debian 13, the release the `dart` image is built on. The image has `/bin/sh` for the web terminal and custom start commands. Dart’s own image documentation copies the executable into an empty `scratch` image instead, which has no shell.
`COPY` without `--chown`, then `USER 1000:1000`	The server runs as a user with no privileges. The executable stays owned by root, so the server can’t change it.
`CMD ["/app/server"]`	The exec form runs the server as process 1, so it receives `SIGTERM` itself, and `main.dart` handles it. The image needs no init process.
`EXPOSE 8080`	Documents Sevalla’s default `PORT`. The server reads `PORT` when it starts.

.dockerignore

.git
.dart_tool
.dart_frog
build
.env*
*.log

The .dockerignore keeps the Git history, Dart’s and Dart Frog’s local folders, a local build folder, local environment files and logs out of the build. Build the image locally to check it:

docker build -t storefront .
docker run --rm -p 8080:8080 storefront

The final image is about 128 MB, the executable 7.5 MB of it. Initialize a Git repository, commit everything and push it to your Git provider:

git init
git add .
git commit -m "Prepare for Sevalla"
git branch -M main
git remote add origin https://github.com/acme/storefront.git
git push -u origin main

Deploy to Sevalla

These steps build from the Dockerfile in Deploy with a Dockerfile. A new application builds with Ingot, which can’t build a Dart project, so choose the Dockerfile build strategy before you deploy.

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.

Choose the Dockerfile build strategy

Click the 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.

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.

Verify the deployment

On the Deployments tab, click the deployment. Its Build log starts the build with 📦 Building and pushing docker image using Dockerfile..., and the dart compile exe step ends with Generated: /app/build/bin/server. The deployment’s Dockerfile tab shows the file the image was built from.
Wait for the deployment’s status to change to Deployed. The application’s status next to its name changes to Running.
Click the domain under the application’s name, for example storefront-x7k2m.sevalla.app. The page shows Welcome to Dart Frog!

The application header with its name, Running status, repository, branch and the domain that opens the application

The application’s runtime logs show ✓ Running on http://:::8080: the server listens on port 8080 of every address. If the deployment fails, read its build log, then see Troubleshoot. To check the deployment from a terminal or an AI agent, read its status with Get deployment (getDeploymentV3) until it’s success, and its build log with Get application deployment logs (getApplicationDeploymentLogsV3), as in Deploy with the API. The build log names the Dockerfile build:

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

📦 Building and pushing docker image using Dockerfile...

Then request the home page:

curl -s -w '\n' https://storefront-x7k2m.sevalla.app/

Welcome to Dart Frog!

Get application runtime logs (getApplicationRuntimeLogsV3) with search finds the address the server listens on. The line starts with color codes for the check mark, which grep -o leaves out:

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

Running on http://:::8080

Shut down gracefully

When Sevalla stops an instance, during a deployment, a restart or a scale-down, it waits 5 seconds, sends SIGTERM, and stops the instance if it’s still running 30 seconds after the shutdown began. See How processes run. The server runs as process 1 in its container, and Linux ignores a signal that process 1 has no handler for. The server that Dart Frog generates installs none, so without main.dart it ignores SIGTERM and keeps running until Sevalla stops it 30 seconds later. With main.dart, the server stops taking new connections on SIGTERM, server.close() waits for the requests in progress to finish, and the process logs Server stopped and exits. That line ends the old instance’s runtime logs on every deployment after the first.

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 from the Dockerfile, then replaces the web process’s instances. When only your code changes, the build log shows CACHED for the steps up to COPY . ., so the build installs nothing again. When you add a package with dart pub add, commit pubspec.yaml and pubspec.lock with the code. See Deployments.

Use environment variables

Add configuration on the application’s Environment variables tab and read it with Platform.environment from dart:io, as the generated server reads PORT. Variables apply at the next deployment. Variables marked Available during buildtime arrive in the Docker build as build arguments, which a stage reads only after an ARG line for each one. See Environment variables.

Add a custom domain

To serve the application from your own domain, such as shop.example.com, add the domain on the application’s Domains tab and create the DNS records that Sevalla shows. Custom domains need a web process larger than H1, so scale the web process first. See Custom domains.

Troubleshoot

Symptom	Cause	Fix
The build log shows `Ingot couldn't tell what kind of application this is`, followed by `Ingot looks for a manifest such as package.json, requirements.txt or go.mod at the root.`	The application builds with Ingot, the default build strategy, which has no Dart provider	Choose the Dockerfile build strategy, as in Deploy to Sevalla, then deploy
The build fails with `"/pubspec.lock": not found`	`pubspec.lock` isn’t in the repository, because Dart Frog’s `.gitignore` leaves it out	Delete the `pubspec.lock` line from `.gitignore`, commit `pubspec.lock` and push
The first Dockerfile build logs `ERROR: failed to configure registry cache importer:`, followed by the application’s image and `:cache: not found`	The application has no build cache yet	Nothing: the build continues, and the next builds use the cache it saves
A deployment waits 30 seconds for the old instance to stop, and its runtime logs never show `Server stopped`	The server doesn’t handle `SIGTERM`	Add `main.dart` from Prepare the project for Sevalla

For more causes, see Troubleshoot builds and deployments.

Deploy with the API

These calls make the same deployment as Deploy to Sevalla, 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 APP:CREATE, APP:READ and APP:UPDATE permissions, 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 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.

Choose the location

List clusters (listClustersV3) returns the locations your company can use, each with its id, the display_name that the dashboard shows and its region ID in location. Keep the ID of the one you want by its region ID, such as eu-frankfurt-1 for Frankfurt, Germany. Locations lists them all:

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.

Create the application

Create application (createApplicationV3) creates the application with a web process. It 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.

Choose the Dockerfile build strategy

The application builds with Ingot (build_type is ingot), which can’t build a Dart project. Update application (updateApplicationV3) switches it to the Dockerfile at the root of the repository:

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 and the same body.

Find the domain

List application domains (listApplicationDomainsV3) returns the domain that Sevalla gives the application. It appears a few seconds after the application is created, so ask until it’s there:

for i in $(seq 1 24); do
  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')
  [ -n "$HOST" ] && break
  sleep 5
done
echo "$HOST"

storefront-x7k2m.sevalla.app

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

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.

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.

Set the size

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

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 -r .resource_type_name

h1

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

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

true

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 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 '{"branch":"main"}' | jq -r .id)

CLI: sevalla apps deployments trigger $APP_ID --branch main. MCP: trigger_deployment.

Wait for the deployment

Get deployment (getDeploymentV3) returns the deployment’s status: waiting and inProgress while it runs, then success, failed, cancelled or skipped. Poll it until the status is final, for up to 30 minutes. The first build takes about a minute:

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"

success

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 checkout, the Docker build and the rollout. When the status is failed, the last lines say why. Without limit, it returns the latest 1,000 lines:

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 --limit 5000. MCP: get_deployment_logs.

Check the application

Request the home page from the application’s domain:

curl -s -w '\n' https://$HOST/

Welcome to Dart Frog!

Then run the other checks in Verify the deployment.

Get started

Migrate

AI

JavaScript

Python

PHP

Ruby

Go

Rust

Java, Kotlin and Scala

.NET

Elixir

Gleam

Swift

Dart

Static site generators

Deploy a Dart Frog application

At a glance

Environment variables

Before you begin

Create the project

Prepare the project for Sevalla

Deploy with a Dockerfile

Deploy to Sevalla

Verify the deployment

Shut down gracefully

Deploy changes

Use environment variables

Add a custom domain

Troubleshoot

Deploy with the API

​At a glance

​Environment variables

​Before you begin

​Create the project

​Prepare the project for Sevalla

​Deploy with a Dockerfile

​Deploy to Sevalla

​Verify the deployment

​Shut down gracefully

​Deploy changes

​Use environment variables

​Add a custom domain

​Troubleshoot

​Deploy with the API

At a glance

Environment variables

Before you begin

Create the project

Prepare the project for Sevalla

Deploy with a Dockerfile

Deploy to Sevalla

Verify the deployment

Shut down gracefully

Deploy changes

Use environment variables

Add a custom domain

Troubleshoot

Deploy with the API