> ## Documentation Index > Fetch the complete documentation index at: https://docs.sevalla.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > These are the docs for Sevalla, a platform for deploying applications, databases, static sites, object storage and load balancers. The dashboard is at https://app.sevalla.com. > Bold text in steps is an exact dashboard label. > To act on a Sevalla account, prefer the Sevalla MCP server (https://mcp.sevalla.com/mcp, see https://docs.sevalla.com/ai-agents/overview.md), then the Sevalla CLI (https://docs.sevalla.com/developer-tools/cli.md), then the REST API (https://api-docs.sevalla.com, OpenAPI spec at https://api.sevalla.com/v3/openapi.json). > Every page index is at https://docs.sevalla.com/llms.txt. # Deploy a Blazor application > Deploy a Blazor Web App with interactive server rendering to Sevalla: WebSockets through the proxy, Data Protection keys in PostgreSQL, and why it runs on one instance. A Blazor Web App runs on Sevalla as an ASP.NET Core application: [Ingot](https://docs.sevalla.com/applications/builds/ingot.md), Sevalla's builder, publishes it with the .NET SDK, and the web process runs `dotnet /app/Storefront.dll` on Microsoft's ASP.NET Core runtime image, listening on the port that Sevalla sets in the `PORT` environment variable. With interactive server rendering, each browser tab keeps a SignalR connection over a WebSocket, called a circuit, to the instance that runs its components. This guide deploys the .NET 10 Blazor template with a form, keeps the application's Data Protection keys in a Sevalla PostgreSQL database so forms and cookies survive deployments, and explains why the web process runs one instance. ## At a glance | | | | - | - | | Source | A Git repository | | Build | [Ingot](https://docs.sevalla.com/applications/builds/ingot.md) (.NET 10 SDK; `ingot.json` adds the EF Core migrations bundle), or the [Dockerfile](#deploy-with-a-dockerfile) | | Start command | `dotnet /app/Storefront.dll` | | Port | The `PORT` environment variable, `8080` by default | | Processes | Web process at 1 instance (see [Run one instance](#run-one-instance)); `Migrate` job (`/app/efbundle`, **Before deployment**) | | Services | PostgreSQL over an internal connection, for the Data Protection keys | | Disk | None | | Health check | None | | Size | **H1** for the web process and the job | ### Environment variables | Variable | Required | Available during | Secret | Value | | - | - | - | - | - | | `DB_HOST` | Yes | Runtime | No | The database's internal hostname, from the internal connection | | `DB_PORT` | Yes | Runtime | No | The database's internal port, `5432`, from the internal connection | | `DB_DATABASE` | Yes | Runtime | No | The database name, from the internal connection | | `DB_USERNAME` | Yes | Runtime | No | The database user, from the internal connection | | `DB_PASSWORD` | Yes | Runtime | Yes | The database password, from the internal connection | | `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](https://docs.sevalla.com/git/overview.md). * The .NET 10 SDK on your computer: `dotnet --version` prints `10.0.100` or later. .NET 10 is the current long-term support release; see [Deploy an ASP.NET Core application](https://docs.sevalla.com/guides/dotnet/aspnet-core.md) for why this guide uses it. ## Create the project Create a Blazor Web App named `Storefront` whose interactive components run on the server: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} dotnet new blazor -o storefront -n Storefront --interactivity Server cd storefront dotnet new gitignore ``` The template's **Counter** page is an interactive server component: each click on **Click me** goes to the server over the circuit's WebSocket. Add a page with a form that Blazor renders on the server without a circuit, and protects with an antiforgery token: ```razor Components/Pages/Subscribe.razor theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} @page "/subscribe" Subscribe

Subscribe

@if (subscribed) {

Thanks, @Form.Email is subscribed.

} else { } @code { [SupplyParameterFromForm] private SubscribeForm Form { get; set; } = new(); private bool subscribed; public class SubscribeForm { public string? Email { get; set; } } } ``` ## Keep the Data Protection keys in PostgreSQL ASP.NET Core encrypts antiforgery tokens, authentication cookies and the state of prerendered interactive components with its Data Protection keys. By default, each instance creates its own keys in its home folder, which every deployment and restart discards. A form that a visitor loaded before a deployment then fails after it: the post returns `400` with an empty page, because the new instance can't read the token. At start, the runtime logs warn about it: ```text Runtime logs theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} warn: Microsoft.AspNetCore.DataProtection.Repositories.FileSystemXmlRepository[60] Storing keys in a directory '/home/ubuntu/.aspnet/DataProtection-Keys' that may not be persisted outside of the container. Protected data will be unavailable when container is destroyed. For more information go to https://aka.ms/aspnet/dataprotectionwarning ``` Store the keys in the database instead, with Entity Framework Core (EF Core). Add the packages and the EF Core command-line tool: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} dotnet add package Microsoft.AspNetCore.DataProtection.EntityFrameworkCore dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL dotnet add package Microsoft.EntityFrameworkCore.Design dotnet new tool-manifest dotnet tool install dotnet-ef ``` | Package or tool | What it does | | - | - | | `Microsoft.AspNetCore.DataProtection.EntityFrameworkCore` | Stores the keys in a table through EF Core | | `Npgsql.EntityFrameworkCore.PostgreSQL` | EF Core's PostgreSQL provider | | `Microsoft.EntityFrameworkCore.Design` | What `dotnet ef` needs to create migrations and the migrations bundle. It isn't published with the application. | | `dotnet-ef` | The EF Core command-line tool, pinned in `dotnet-tools.json` so every build uses the same version | Add a database context for the keys: ```csharp KeysDb.cs theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} using Microsoft.AspNetCore.DataProtection.EntityFrameworkCore; using Microsoft.EntityFrameworkCore; public class KeysDb(DbContextOptions options) : DbContext(options), IDataProtectionKeyContext { public DbSet DataProtectionKeys => Set(); } ``` In `Program.cs`, add the `using` lines at the top and the connection, the context and the key storage before `AddRazorComponents`. The rest is the template's: ```csharp Program.cs theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} using Microsoft.AspNetCore.DataProtection; using Microsoft.EntityFrameworkCore; using Npgsql; using Storefront.Components; var builder = WebApplication.CreateBuilder(args); // The internal connection to the database adds DB_HOST, DB_PORT, DB_DATABASE, DB_USERNAME and DB_PASSWORD var config = builder.Configuration; var connectionString = new NpgsqlConnectionStringBuilder { Host = config["DB_HOST"] ?? "localhost", Port = int.Parse(config["DB_PORT"] ?? "5432"), Database = config["DB_DATABASE"] ?? "storefront", Username = config["DB_USERNAME"] ?? "postgres", Password = config["DB_PASSWORD"], // The .NET images don't include Kerberos, which Npgsql otherwise tries to load GssEncryptionMode = GssEncryptionMode.Disable, }.ConnectionString; // Keep the Data Protection keys in PostgreSQL, so every instance and deployment shares them builder.Services.AddDbContext(options => options.UseNpgsql(connectionString)); builder.Services.AddDataProtection().PersistKeysToDbContext(); // Add services to the container. builder.Services.AddRazorComponents() .AddInteractiveServerComponents(); var app = builder.Build(); // Configure the HTTP request pipeline. if (!app.Environment.IsDevelopment()) { app.UseExceptionHandler("/Error", createScopeForErrors: true); // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts. app.UseHsts(); } app.UseStatusCodePagesWithReExecute("/not-found", createScopeForStatusCodePages: true); app.UseHttpsRedirection(); app.UseAntiforgery(); app.MapStaticAssets(); app.MapRazorComponents() .AddInteractiveServerRenderMode(); app.Run(); ``` ASP.NET Core reads environment variables into its configuration, so `config["DB_HOST"]` is the `DB_HOST` variable. Npgsql takes a connection string of keys and values rather than the `postgres://` URL in `DB_URL`, so the code builds one from the separate variables. Create the migration that adds the `DataProtectionKeys` table, then write the lock file of the exact package versions: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} dotnet ef migrations add DataProtectionKeys dotnet restore --use-lock-file ``` With the keys in the database, the warning is gone. ASP.NET Core still logs `No XML encryptor configured` when it creates a key: it stores the keys unencrypted, so anyone who can read the database can read them. Keep the database's credentials as private as the keys themselves. ## Prepare the project for Sevalla The migrations run from a [migrations bundle](https://learn.microsoft.com/ef/core/managing-schemas/migrations/applying#bundles): a single executable that `dotnet ef` builds next to the application, which applies the pending migrations and needs neither the SDK nor the source. Ingot's own build step publishes the application only, so tell it to build the bundle too, in an `ingot.json` file at the root of the repository: ```json ingot.json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} { // Publish the application, then build the migrations bundle next to it "build": "dotnet publish -c Release -o /app/publish -p:UseAppHost=false && dotnet tool restore && dotnet ef migrations bundle --configuration Release --no-build -o /app/publish/efbundle" } ``` A custom build command must publish to `/app/publish`: Ingot copies that folder to `/app` in the image, so the bundle runs as `/app/efbundle`. See [Configure the build](https://docs.sevalla.com/applications/builds/ingot.md#configure-the-build). | File | Why Sevalla needs it | | - | - | | `Storefront.csproj` | Ingot finds the project at the root of the repository, reads its `TargetFramework` (`net10.0`) to build with the .NET 10 SDK and run on the ASP.NET Core 10 image, and starts the assembly it builds, `Storefront.dll`. See [Pin the .NET version](https://docs.sevalla.com/guides/dotnet/overview.md#pin-the-net-version). | | `packages.lock.json` | Ingot restores the packages with `dotnet restore --locked-mode`, so the build gets exactly the versions you tested, or fails. | | `dotnet-tools.json` | Pins the version of `dotnet-ef` that builds the migrations bundle | | `ingot.json` | Builds the migrations bundle with the application | | `Migrations/` | The migration that the job applies | Ingot needs no other configuration. It detects ASP.NET Core and, in the image it builds, points `ASPNETCORE_HTTP_PORTS` at the `PORT` variable, so Kestrel listens on the web process's port, `8080` by default, and sets `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true`, so the application takes the scheme from the `X-Forwarded-Proto` header of Sevalla's proxy: requests are HTTPS, and the template's `UseHttpsRedirection` and `UseHsts` work without a redirect loop. Commit everything and push it to your Git provider: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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 with [Ingot](https://docs.sevalla.com/applications/builds/ingot.md). To build from your own Dockerfile instead, see [Deploy with a Dockerfile](#deploy-with-a-dockerfile). **1. Create the database** In the sidebar, click **Databases**, then click **Create database**. Under **Database**, choose **PostgreSQL** and the newest version. Enter `orders-db` as the **Display name**, choose a **Data center** and a **Size**, then click **Create database**. See [Create a database](https://docs.sevalla.com/databases/create.md) for every field. **2. 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. **3. 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**. Sevalla adds `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD` and `DB_URL` to the application. See [Connect an application](https://docs.sevalla.com/databases/connect.md#connect-an-application). **4. Create the migration job** Click the **Processes** tab, then click **Create process**. Choose **Job**, enter `Migrate` as the **Name** and `/app/efbundle` as the **Custom start command**. Keep the **Start policy** at **Before deployment** and the **Resource** at **H1**, then click **Create process**. **5. Deploy** Click the **Overview** tab, then click **Deploy now** under **Recent deployments**. Check the **Branch** and click **Deploy**. **6. 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](https://docs.sevalla.com/applications/deployments.md#deploy-automatically-on-push). ## Verify the deployment 1. On the **Deployments** tab, click the deployment. Its **Build log** shows Ingot's [build plan](https://docs.sevalla.com/applications/builds/ingot.md#read-the-build-plan): .NET 10 from the project's `TargetFramework`, ASP.NET Core and the start command. ```text Build log theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} ╭─ ■ ASP.NET Core · .NET 10 ─────────────────────────────────────────────────────────╮ │ .NET 10 Storefront.csproj TargetFramework "net10.0" │ │ Project Storefront.csproj the only project │ │ Framework ASP.NET Core Storefront.csproj │ │ Start dotnet /app/Storefront.dll Storefront.csproj │ ├─ Image ────────────────────────────────────────────────────────────────────────────┤ │ Build mcr.microsoft.com/dotnet/sdk:10.0-noble │ │ Runtime mcr.microsoft.com/dotnet/aspnet:10.0-noble │ │ User 1000:1000 │ │ Init tini │ │ Port $PORT, default 8080 │ ╰───────────────────────────────────────────────────────────────────── Ingot v0.4.1 ─╯ ``` During the rollout, the build log shows `Migrate has been successful`. If the job fails, the deployment fails and the previous version keeps running. 2. Wait for the deployment's status to change to **Deployed**, then click the domain under the application's name, for example `storefront-x7k2m.sevalla.app`. The template's home page shows `Hello, world!`. 3. Click **Counter**, then click **Click me** three times. The page shows `Current count: 3`: the clicks reached the server over a WebSocket to `wss://storefront-x7k2m.sevalla.app/_blazor`, which Sevalla's proxy passes through with no settings. 4. Add `/subscribe` to the address, enter an email address and click **Subscribe**. The page shows `Thanks, ana@example.com is subscribed.` Load the form again, deploy, then submit it: it still works, because the new instance reads the keys from the database. ![The application header with its name, Running status, repository, branch and the domain that opens the application](https://assets.sevalla.com/screenshots/light/app-overview-address.png) If the deployment fails, read its build log, then see [Troubleshoot Ingot builds](https://docs.sevalla.com/applications/builds/ingot.md#troubleshoot-ingot-builds). To check the deployment from a terminal or an AI agent, read its `status` with [Get deployment](https://api-docs.sevalla.com/v3/applications/get-deployment) (`getDeploymentV3`) until it's `success`, and its build log with [Get application deployment logs](https://api-docs.sevalla.com/v3/applications/get-application-deployment-logs) (`getApplicationDeploymentLogsV3`), as in [Deploy with the API](#deploy-with-the-api). Then ask for a circuit the way the browser does: the negotiate request lists the transports the server offers, WebSockets first: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} curl -s -X POST 'https://storefront-x7k2m.sevalla.app/_blazor/negotiate?negotiateVersion=1' | jq -r '.availableTransports[].transport' ``` ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} WebSockets ServerSentEvents LongPolling ``` [Get application runtime logs](https://api-docs.sevalla.com/v3/applications/get-application-runtime-logs) (`getApplicationRuntimeLogsV3`) with `search` finds the migration that the `Migrate` job applied: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} curl -s "https://api.sevalla.com/v3/applications/$APP_ID/runtime-logs?search=Applying%20migration" \ -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.[].message' ``` ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} Applying migration '20261029185426_DataProtectionKeys'. Applying migration '20261029185426_DataProtectionKeys'. ``` The migration's name starts with the time you created it, so yours differs. ## Run one instance Keep the web process at 1 instance, and give it a larger [size](https://docs.sevalla.com/applications/scaling.md) when it needs more capacity. A circuit lives in the memory of one instance, and SignalR opens it with two requests: a `POST` to `/_blazor/negotiate`, then the WebSocket. Sevalla's proxy has no sticky sessions, so with 2 or more instances the two requests can reach different instances. Every page load where they do fails to connect (4 of 8 in a test with 2 instances), and the browser's console shows: ```text Browser console theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} Error: Failed to start the transport 'WebSockets': Error: WebSocket failed to connect. The connection could not be found on the server, either the endpoint may not be a SignalR endpoint, the connection ID is not present on the server, or there is a proxy blocking WebSockets. If you have multiple servers check that sticky sessions are enabled. ``` To run several instances, render the interactive components with WebAssembly instead (`--interactivity WebAssembly` when you create the project): they run in the browser and need no circuit. Azure SignalR Service, Microsoft's other answer to scaling out Blazor Server, is outside the scope of this guide. A deployment replaces the instance, so it ends every open circuit. The template's reconnection dialog tries to rejoin, the new instance rejects the unknown circuit, and the page reloads: the state of interactive components, such as the counter, starts over. ## Deploy with a Dockerfile Ingot needs no Dockerfile. Write one when you want full control of the image: the base image, system packages and every layer. Add a `Dockerfile` and a `.dockerignore` to the root of the repository: ```dockerfile Dockerfile theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} FROM mcr.microsoft.com/dotnet/sdk:10.0-noble AS build ENV DOTNET_CLI_TELEMETRY_OPTOUT=1 WORKDIR /src COPY dotnet-tools.json Storefront.csproj packages.lock.json ./ # Without the .razor files, the SDK would leave out the package of Blazor's scripts that the lock file lists RUN dotnet restore --locked-mode -p:RequiresAspNetWebAssets=true && dotnet tool restore COPY . . RUN dotnet publish --no-restore -c Release -o /app -p:UseAppHost=false \ && dotnet ef migrations bundle --configuration Release --no-build -o /app/efbundle FROM mcr.microsoft.com/dotnet/aspnet:10.0-noble WORKDIR /app COPY --from=build /app . ENV ASPNETCORE_FORWARDEDHEADERS_ENABLED=true USER 1654 EXPOSE 8080 CMD ["/bin/sh", "-c", "ASPNETCORE_HTTP_PORTS=${PORT:-8080} exec dotnet Storefront.dll"] ``` | Line or choice | Why | | - | - | | `sdk:10.0-noble`, `aspnet:10.0-noble` | The .NET 10 images on Ubuntu 24.04 that Ingot uses too. The `10.0` tag moves to each patch release, so a rebuild picks up security fixes; a digest would freeze them. Microsoft's chiseled images have no shell, which the [web terminal](https://docs.sevalla.com/applications/web-terminal.md) and start commands need. | | Two stages | The SDK builds in the first stage. The final image holds the published application, its static files, the bundle and the ASP.NET Core runtime only. | | Project files before the source | `dotnet restore` runs on the project file, the lock file and the tool manifest alone, so its layer is reused when only code changes. `--locked-mode` fails the build if the lock file is out of date. | | `-p:RequiresAspNetWebAssets=true` | The SDK adds a package of Blazor's scripts, which the lock file lists, only when it sees `.razor` files, and they aren't copied yet. The property adds it anyway, so the restore matches the lock file, and `dotnet publish --no-restore` uses that restore. | | `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true` | The same setting as Ingot's: requests are HTTPS behind Sevalla's proxy. | | `USER 1654` | The `app` user of Microsoft's images (`APP_UID`). The files in `/app` belong to root, so the application can read them but not change them. The keys are in the database, so it writes nothing to disk. | | `CMD` | The shell points `ASPNETCORE_HTTP_PORTS` at the `PORT` variable, then `exec` replaces itself with `dotnet`. .NET runs as process 1 and receives `SIGTERM` when Sevalla stops an instance: it logs `Application is shutting down...` and stops gracefully, so it needs no init process such as `tini`. `EXPOSE 8080` documents the default port. | ```text .dockerignore theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} .git **/bin **/obj .vs .vscode .env* *.log wwwroot/lib/**/*.map Dockerfile .dockerignore ``` The template ships Bootstrap with its source maps, 6 MB that the application doesn't need, so `.dockerignore` leaves them out of the image. Commit and push both files. Ingot doesn't use the `Dockerfile`, so you can keep it in a repository that builds with Ingot, but it adds the `.dockerignore` patterns to its own (its build plan shows `Ignored 10 patterns from .dockerignore`), and the Ingot build passes with this file. Then switch the application to the Dockerfile build strategy: **1. 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**. **2. Deploy** Click the **Overview** tab, then click **Deploy now** under **Recent deployments**. Check the **Branch** and click **Deploy**. The build log starts the build with `📦 Building and pushing docker image using Dockerfile...` instead of Ingot's build plan, and still shows `Migrate has been successful`. The **Counter** and **Subscribe** pages work as in [Verify the deployment](#verify-the-deployment), and a form loaded before the deployment still submits. The deployment's **Dockerfile** tab shows the file the image was built from. When you push a change to the code only, the build log shows `CACHED` for the `dotnet restore` step. With the API, [Update application](https://api-docs.sevalla.com/v3/applications/update-application) (`updateApplicationV3`) switches the build strategy. Then deploy and wait as in [Deploy with the API](#deploy-with-the-api): ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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}' ``` ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} {"build_type":"dockerfile","dockerfile_path":"Dockerfile","docker_context":"."} ``` The CLI does the same with `sevalla apps update $APP_ID --build-type dockerfile --dockerfile-path Dockerfile`. The new deployment's build log names the Dockerfile build: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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' ``` ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 📦 Building and pushing docker image using Dockerfile... ``` ## 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, runs the `Migrate` job, then replaces the web process's instance, which ends the open circuits. Without a readiness probe, the new instance gets requests as soon as its container starts, a moment before Kestrel listens, and they fail with `503`: turn on a [readiness probe](https://docs.sevalla.com/guides/dotnet/aspnet-core.md#turn-on-the-readiness-probe) with the **Path** `/`. The probe calls the instance over plain HTTP, so each instance logs `Failed to determine the https port for redirect.` once; the warning is harmless. To add tables, add a `DbSet` to a context, run `dotnet ef migrations add ` locally and commit the new files in `Migrations/`. When you add or update a package, `dotnet add package` updates `packages.lock.json`: commit it too. See [Deployments](https://docs.sevalla.com/applications/deployments.md). ## Use environment variables Add variables on the application's **Environment variables** tab; they apply at the next deployment. ASP.NET Core reads every environment variable into its configuration: read `PAYMENT_API_URL` with `builder.Configuration["PAYMENT_API_URL"]`, or inject `IConfiguration` into a component, and write a nested setting such as `ConnectionStrings:Default` as `ConnectionStrings__Default`. See [Environment variables](https://docs.sevalla.com/applications/environment-variables.md). ## 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. The template allows every host and SignalR accepts the connection on any domain the application serves, so the application needs no change. Custom domains need a web process larger than **H1**, so [scale](https://docs.sevalla.com/applications/scaling.md) the web process first. See [Custom domains](https://docs.sevalla.com/domains/overview.md). ## Troubleshoot | Symptom | Cause | Fix | | - | - | - | | A form returns `400` with an empty page after a deployment or restart | The Data Protection keys aren't persisted, so the new instance can't read the antiforgery token. | Store the keys in the database, as in [Keep the Data Protection keys in PostgreSQL](#keep-the-data-protection-keys-in-postgresql). | | Interactive components don't respond on some page loads, and the browser console shows `If you have multiple servers check that sticky sessions are enabled.` | The web process runs more than one instance. | Scale the web process to 1 instance. See [Run one instance](#run-one-instance). | | A Dockerfile build fails at `dotnet restore` with `error NU1004: The package references have changed for net10.0. Lock file's package references: Microsoft.AspNetCore.App.Internal.Assets` | The restore runs before the `.razor` files are copied, so the SDK leaves out the package of Blazor's scripts that the lock file lists. | Add `-p:RequiresAspNetWebAssets=true` to `dotnet restore`, as in [Deploy with a Dockerfile](#deploy-with-a-dockerfile). | | The runtime logs show `Cannot load library libgssapi_krb5.so.2` | The connection string doesn't turn off `GssEncryptionMode`. | Set `GssEncryptionMode = GssEncryptionMode.Disable`, as in `Program.cs`. | For more causes, see [Troubleshoot Ingot builds](https://docs.sevalla.com/applications/builds/ingot.md#troubleshoot-ingot-builds). ## Deploy with the API These calls make the same deployment as [Deploy to Sevalla](#deploy-to-sevalla), in an order that a script or an AI agent runs as it is. Each step names the [Sevalla API](https://docs.sevalla.com/developer-tools/api.md) operation, then the [CLI](https://docs.sevalla.com/developer-tools/cli.md) command and the [MCP server](https://docs.sevalla.com/ai-agents/overview.md) tool that do the same. You need: * An [API key](https://docs.sevalla.com/developer-tools/api-keys.md) with the **Company developer** role, or the `APP:CREATE`, `APP:READ`, `APP:UPDATE`, `DATABASE:CREATE`, `DATABASE:READ` and `DATABASE: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](https://docs.sevalla.com/git/overview.md). 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`, `jq` and `openssl`. **1. Choose the location** [List clusters](https://api-docs.sevalla.com/v3/resources/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](https://docs.sevalla.com/platform/locations.md) lists them all. The database and the application must be in the same location: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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`. **2. Find the newest PostgreSQL version** [List database versions](https://api-docs.sevalla.com/v3/resources/list-database-versions) (`listDatabaseVersionsV3`) returns the versions you can create in the location: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} PG_VERSION=$(curl -s "https://api.sevalla.com/v3/resources/database-versions?cluster_id=$CLUSTER_ID&type=postgresql" \ -H "Authorization: Bearer $SEVALLA_API_KEY" \ | jq -r '.[0].versions | max_by(tonumber)') echo "$PG_VERSION" ``` ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 18 ``` CLI: `sevalla resources db-versions --cluster $CLUSTER_ID --type postgresql`. MCP: `create_database` picks the newest version when you leave `version` out. **3. Find the DB1 size** [List database resource types](https://api-docs.sevalla.com/v3/resources/list-database-resource-types) (`listDatabaseResourceTypesV3`) returns the database sizes by `name`. **DB1**, the smallest, is the dashboard's default: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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`. **4. Create the database** [Create database](https://api-docs.sevalla.com/v3/databases/create-database) (`createDatabaseV3`) needs a password: generate one and keep it, because [Get database](https://api-docs.sevalla.com/v3/databases/get-database) (`getDatabaseV3`) doesn't return it. The call returns at once, with the status `creating`: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} DB_PASSWORD=$(openssl rand -hex 16) 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":"'"$PG_VERSION"'","cluster_id":"'"$CLUSTER_ID"'","resource_type_id":"'"$DB_SIZE_ID"'","db_name":"orders","db_user":"storefront","db_password":"'"$DB_PASSWORD"'"}' \ | jq -r .id) ``` CLI: `sevalla databases create --name orders-db --type postgresql --db-version $PG_VERSION --cluster $CLUSTER_ID --resource-type $DB_SIZE_ID --db-name orders --db-user storefront --db-password $DB_PASSWORD`. MCP: `create_database`, which generates the password and doesn't return it, so use this call when the application needs the password itself. **5. Wait for the database** [Get database](https://api-docs.sevalla.com/v3/databases/get-database) (`getDatabaseV3`) returns the status, `creating` and then `ready` once the database accepts connections, and the internal hostname and port that the application connects to: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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=$(echo "$DB" | jq -r '.status // empty') case $STATUS in ready|error) break ;; esac sleep 15 done echo "$STATUS" DB_HOST=$(echo "$DB" | jq -r .internal_hostname) DB_PORT=$(echo "$DB" | jq -r .internal_port) DB_DATABASE=$(echo "$DB" | jq -r .db_name) DB_USERNAME=$(echo "$DB" | jq -r .db_user) ``` ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} ready ``` CLI: `sevalla databases get $DB_ID`. MCP: `get_database`. **6. Create the application** [Create application](https://api-docs.sevalla.com/v3/applications/create-application) (`createApplicationV3`) creates the application with a web process. It builds with Ingot (`build_type` is `ingot`) and isn't deployed yet: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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`. **7. Find the domain** [List application domains](https://api-docs.sevalla.com/v3/applications/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: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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" ``` ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} storefront-x7k2m.sevalla.app ``` CLI: `sevalla apps domains list --app-id $APP_ID`. MCP: `get_application`. **8. Connect the database** [Create internal connection](https://api-docs.sevalla.com/v3/applications/create-internal-connection) (`createApplicationInternalConnectionV3`) connects the application to the database over the private network and returns the connection's `id`. Unlike the dashboard, it doesn't add environment variables: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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_id":"'"$DB_ID"'","target_type":"database"}' ``` CLI: `sevalla apps internal-connections create $APP_ID --target-id $DB_ID --target-type database`. MCP: `sevalla_api_create` with `createApplicationInternalConnectionV3`. **9. Add the connection variables** [Create environment variable](https://api-docs.sevalla.com/v3/applications/create-environment-variable) (`createEnvironmentVariableV3`) adds the five variables that `Program.cs` reads, with the names and values that the dashboard's internal connection adds, available at runtime only. The dashboard also adds `DB_URL`, which this application doesn't read: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} for VAR in "DB_HOST=$DB_HOST" "DB_PORT=$DB_PORT" "DB_DATABASE=$DB_DATABASE" "DB_USERNAME=$DB_USERNAME" "DB_PASSWORD=$DB_PASSWORD"; do 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 kv "$VAR" '{key: ($kv | sub("=.*"; "")), value: ($kv | sub("^[^=]*="; "")), is_runtime: true, is_buildtime: false}')" \ | jq -c '{key, is_runtime, is_buildtime}' done ``` ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} {"key":"DB_HOST","is_runtime":true,"is_buildtime":false} {"key":"DB_PORT","is_runtime":true,"is_buildtime":false} {"key":"DB_DATABASE","is_runtime":true,"is_buildtime":false} {"key":"DB_USERNAME","is_runtime":true,"is_buildtime":false} {"key":"DB_PASSWORD","is_runtime":true,"is_buildtime":false} ``` CLI: `sevalla apps env-vars create $APP_ID --key DB_HOST --value $DB_HOST`, once per variable; it always makes a variable available during the build and runtime. MCP: `set_environment_variables` with `buildtime` set to `false`. **10. Find the web process** [List processes](https://api-docs.sevalla.com/v3/applications/list-processes) (`listProcessesV3`) returns the web process that the application was created with: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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`. **11. Find the H1 size** [List process resource types](https://api-docs.sevalla.com/v3/resources/list-process-resource-types) (`listProcessResourceTypesV3`) returns the sizes by `name`, in lowercase: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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`. **12. Create the migration job** [Create process](https://api-docs.sevalla.com/v3/applications/create-process) (`createProcessV3`) creates the `Migrate` job. The API needs the size, a `scaling_strategy` and the `job_start_policy`, which the dashboard fills in for you: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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":"/app/efbundle","resource_type_id":"'"$H1_ID"'","scaling_strategy":{"type":"manual","config":{"instanceCount":1}},"job_start_policy":"beforeDeployment"}' \ | jq -c '{display_name, type, entrypoint, job_start_policy, resource_type_name}' ``` ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} {"display_name":"Migrate","type":"job","entrypoint":"/app/efbundle","job_start_policy":"beforeDeployment","resource_type_name":"h1"} ``` CLI: `sevalla apps processes create $APP_ID --name Migrate --type job --command /app/efbundle --resource-type $H1_ID --job-start-policy beforeDeployment`. MCP: `sevalla_api_create` with `createProcessV3` and the same body. **13. Set the size** The API creates the web process at **S1**, where the dashboard's default is **H1**. [Update process](https://api-docs.sevalla.com/v3/applications/update-process) (`updateProcessV3`) sets the size: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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 ``` ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} h1 ``` CLI: `sevalla apps processes update $WEB_ID --app-id $APP_ID --resource-type $H1_ID`. MCP: `scale_process` with `size_id`. **14. Turn on auto-deploy** [Update application](https://api-docs.sevalla.com/v3/applications/update-application) (`updateApplicationV3`) turns on automatic deployments for every push to the branch: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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`. **15. Deploy** [Trigger deployment](https://api-docs.sevalla.com/v3/applications/trigger-deployment) (`triggerDeploymentV3`) deploys the latest commit on the branch: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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`. **16. Wait for the deployment** [Get deployment](https://api-docs.sevalla.com/v3/applications/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: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} 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" ``` ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} success ``` CLI: `sevalla apps deployments get $DEPLOYMENT_ID --app-id $APP_ID`. MCP: `get_deployment`. **17. Read the build log** [Get application deployment logs](https://api-docs.sevalla.com/v3/applications/get-application-deployment-logs) (`getApplicationDeploymentLogsV3`) returns the build log, oldest line first: the build plan from [Verify the deployment](#verify-the-deployment), the build and the rollout. When the status is `failed`, the last lines say why. With `search`, it finds the job's result: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} curl -s "https://api.sevalla.com/v3/applications/$APP_ID/deployments/$DEPLOYMENT_ID/logs?search=Migrate%20has" \ -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.[].message' ``` ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} ✅ Migrate has been successful ``` CLI: `sevalla apps deployments logs $DEPLOYMENT_ID --app-id $APP_ID`. MCP: `get_deployment_logs`. **18. Check the application** Request the home page from the application's domain: ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} curl -s https://$HOST/ | grep -o -m1 'Hello, world!' ``` ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}} Hello, world! ``` Then run the other checks in [Verify the deployment](#verify-the-deployment). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.