Skip to main content
A Leptos application with server-side rendering runs on Sevalla as one Rust binary and a folder of site files: cargo-leptos compiles the Axum server that renders each page to HTML, and the WebAssembly bundle that the browser loads to make the page interactive (hydration). Sevalla builds both from a Dockerfile in your repository, because Ingot, Sevalla’s builder, doesn’t run cargo-leptos. The web process runs the server, which listens on the port that Sevalla sets in the PORT environment variable.

At a glance

Environment variables

Before you begin

Create the project

Create a project from Leptos’s Axum starter:
The starter asks one question, Use nightly features?. CARGO_GENERATE_VALUE_NIGHTLY=No answers it without a prompt, so the project builds on stable Rust, as the Dockerfile does. The project depends on Leptos 0.8 and Axum 0.8, and its Cargo.toml has a [package.metadata.leptos] section that tells cargo-leptos what to build:
  • The server, the storefront binary, with the ssr feature, into target/release.
  • The browser’s code, the library, with the hydrate feature, for the wasm32-unknown-unknown target, then wasm-bindgen and wasm-opt turn it into pkg/storefront.wasm and pkg/storefront.js in target/site.
  • The stylesheet and the files in public, also into target/site.
In src/app.rs, change the page title to <Title text="Storefront"/>, then replace the HomePage component at the end of the file with a page that loads products from a server function:
src/app.rs
The server renders the products into the HTML of the page, and the button counts clicks once the WebAssembly bundle has loaded in the browser.

Prepare the project for Sevalla

The starter’s server listens on 127.0.0.1:3000 and stops at once when Sevalla stops it. Replace src/main.rs, so the server listens on PORT on all network interfaces, answers a health check, and shuts down gracefully:
src/main.rs
Then change three files:
  1. In Cargo.toml, add "signal" to Tokio’s features, which the shutdown handler uses, and point style-file at a CSS file:
    Cargo.toml
    Cargo.toml
  2. Rename the stylesheet to match, with mv style/main.scss style/main.css. The starter’s SCSS is plain CSS, which cargo-leptos optimizes with Lightning CSS, built in. For an .scss file, cargo-leptos downloads Dart Sass during every build.
  3. In .gitignore, delete the line Cargo.lock, so the lock file is committed and every build uses the versions you tested.
Add a rust-toolchain.toml at the root of the project, so rustup on your computer uses Rust 1.99 with the WebAssembly target:
rust-toolchain.toml
Run cargo leptos watch and open http://127.0.0.1:3000 to check the application locally: the page lists the two products, and the button counts your clicks.

Deploy with a Dockerfile

Ingot can’t build a cargo-leptos project. It builds Rust with cargo auditable build --release --locked, which compiles the server without the ssr feature, so its main function is the empty one at the end of src/main.rs, and builds no WebAssembly bundle: Ingot doesn’t run cargo-leptos. The image builds, but the server exits as soon as it starts. The Dockerfile runs cargo-leptos instead. Add a Dockerfile and a .dockerignore to the root of the repository:
Dockerfile
.dockerignore
The .dockerignore keeps the Git history, local environment files, logs, your local target folder of build output and the Playwright tests in end2end out of the build. Commit everything and push it to your Git provider. cargo leptos new already created a Git repository:

Deploy to Sevalla

These steps build from the Dockerfile. New applications build with Ingot, so the second step switches the build strategy before the first deployment.
1

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.
2

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.
3

Deploy

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

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

  1. On the Deployments tab, click the deployment. Its Build log shows 📦 Building and pushing docker image using Dockerfile..., then each step of the Dockerfile, and its Dockerfile tab shows your file. The first build compiles every dependency twice, for the server and for the browser, and the deployment takes about 5 minutes. Later builds reuse the dependency layers and compile only your crate.
  2. Wait for the deployment’s status to change to Deployed. The application’s status next to its name changes to Running.
  3. Click the domain under the application’s name, for example storefront-x7k2m.sevalla.app. The page shows Storefront, the two products and the Click Me button, which counts your clicks once the WebAssembly bundle has loaded.
The application header with its name, Running status, repository, branch and the domain that opens the applicationThe application header with its name, Running status, repository, branch and the domain that opens the application
The application’s runtime logs show listening on http://0.0.0.0:8080. 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. Then request the page, the server function, the WebAssembly bundle and the health check. The server renders the title and the products into the HTML:
Get application runtime logs (getApplicationRuntimeLogsV3) with search finds the start of the server:

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. A Rust program that doesn’t handle SIGTERM ignores it when it runs as process 1, as the server does in the Dockerfile, and Sevalla then stops it only after the 30 seconds. shutdown_signal listens for SIGTERM with Tokio, and with_graceful_shutdown then stops accepting connections and waits for the requests in progress before axum::serve returns. On every deployment, the old instance’s runtime logs end with:
Runtime logs

Add a health check

A readiness probe makes each new instance wait for /healthz to answer before it gets traffic, so a deployment switches over only to instances that serve requests.
1

Open the web process

On the application’s Processes tab, click ⋯ on the Web process, then click Update process.
2

Turn on the readiness probe

Under Health checks, turn on Readiness probe and set the Path to /healthz. Keep the Port at the web process’s port, 8080 unless you changed it.
3

Save and deploy

Click Update process, then click Deploy in the undeployed changes bar at the bottom of the page.
The deployment’s status changes to Deployed once the new instance answers the probe. See Health checks for every probe setting. Deploy with the API sets the same probe. Get process (getProcessV3) returns it in readiness_probe:

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. With Cache enabled in the build strategy, a deployment of a code change shows the dependency step as CACHED in the build log and compiles only your crate. When you add or update a crate, commit Cargo.toml and Cargo.lock with the code; if wasm-bindgen changes version in Cargo.lock, change wasm-bindgen-cli@ in the Dockerfile to match. See Deployments.

Use environment variables

Add configuration on the application’s Environment variables tab and read it in server code with std::env::var, as the server reads PORT. Code that runs in the browser can’t read them. Leptos reads its own settings from LEPTOS_* variables when the server starts, such as LEPTOS_SITE_ROOT, which the Dockerfile sets. Variables apply at the next deployment, and with the Dockerfile, variables marked Available during buildtime arrive 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

For more causes, see Dockerfile and Troubleshoot builds and deployments.

Deploy with the API

These calls make the same deployment as Deploy to Sevalla and Add a health check, 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.
1

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:
CLI: sevalla resources clusters. MCP: get_platform_options.
2

Create the application

Create application (createApplicationV3) creates the application with a web process. It isn’t deployed yet:
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.
3

Choose the Dockerfile build strategy

The application builds with Ingot (build_type is ingot), which can’t build this project. Update application (updateApplicationV3) switches it to the Dockerfile, and turns on automatic deployments for every push to the branch:
CLI: sevalla apps update $APP_ID --data '{"build_type":"dockerfile","dockerfile_path":"Dockerfile","docker_context":".","auto_deploy":true}'. MCP: sevalla_api_update with updateApplicationV3 and the same body.
4

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:
CLI: sevalla apps domains list --app-id $APP_ID. MCP: get_application.
5

Find the web process

List processes (listProcessesV3) returns the web process that the application was created with:
CLI: sevalla apps processes list --app-id $APP_ID. MCP: get_application.
6

Find the H1 size

List process resource types (listProcessResourceTypesV3) returns the sizes by name, in lowercase:
CLI: sevalla resources process-types. MCP: get_platform_options.
7

Set the size and the readiness probe

The API creates the web process at S1, where the dashboard’s default is H1. Update process (updateProcessV3) sets the size and adds the readiness probe from Add a health check, with the dashboard’s default timings. Send timeoutSeconds: a probe without it gets 120 seconds, where the dashboard sets 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 for the size, and sevalla_api_update with updateProcessV3 and the same body for the probe.
8

Deploy

Trigger deployment (triggerDeploymentV3) deploys the latest commit on the branch:
CLI: sevalla apps deployments trigger $APP_ID --branch main. MCP: trigger_deployment.
9

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:
CLI: sevalla apps deployments get $DEPLOYMENT_ID --app-id $APP_ID. MCP: get_deployment.
10

Read the build log

Get application deployment logs (getApplicationDeploymentLogsV3) returns the build log, oldest line first: each step of the Dockerfile, then the rollout. When the status is failed, the last lines say why. With search, it finds the line that names the Dockerfile build:
Without search, add ?limit=5000 to read the whole build log. CLI: sevalla apps deployments logs $DEPLOYMENT_ID --app-id $APP_ID. MCP: get_deployment_logs.
11

Check the application

Request the page from the application’s domain:
Then run the other checks in Verify the deployment.