> ## 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 an ASP.NET Core application

> Deploy an ASP.NET Core minimal API on .NET 10 to Sevalla: Ingot publishes it, a job applies EF Core migrations to PostgreSQL, and a health check gates traffic.

An ASP.NET Core application runs on Sevalla as an application: [Ingot](https://docs.sevalla.com/applications/builds/ingot.md), Sevalla's builder, finds the project file, 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. This guide deploys a minimal API on .NET 10 that reads products from a Sevalla PostgreSQL database with Entity Framework Core (EF Core), applies its migrations in a job before each deployment, and answers a health check that the readiness probe uses.

.NET 10 is the current long-term support (LTS) release, supported until Nov 14, 2028, and the line Ingot builds when a project doesn't say otherwise. .NET 9, the previous standard-term release, reaches end of support on Nov 10, 2026.

## 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; `Migrate` job (`/app/efbundle`, **Before deployment**) |
| Services | PostgreSQL over an internal connection |
| Disk | None |
| Health check | `GET /healthz` returns `200` with `Healthy` when the database answers (readiness probe) |
| 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.

## Create the project

Create an empty ASP.NET Core project named `Storefront`, then add the packages and the EF Core command-line tool:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
dotnet new web -o storefront -n Storefront
cd storefront
dotnet new gitignore
dotnet add package Npgsql.EntityFrameworkCore.PostgreSQL
dotnet add package Microsoft.EntityFrameworkCore.Design
dotnet add package Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore
dotnet new tool-manifest
dotnet tool install dotnet-ef
```

| Package or tool | What it does |
| - | - |
| `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. |
| `Microsoft.Extensions.Diagnostics.HealthChecks.EntityFrameworkCore` | A health check that asks the database for a connection |
| `dotnet-ef` | The EF Core command-line tool, pinned in `dotnet-tools.json` so every build uses the same version |

Add the data model and its database context, with two products that the first migration inserts:

```csharp StoreDb.cs theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
using Microsoft.EntityFrameworkCore;

public class Product
{
    public int Id { get; set; }
    public required string Name { get; set; }
    public decimal Price { get; set; }
}

public class StoreDb(DbContextOptions<StoreDb> options) : DbContext(options)
{
    public DbSet<Product> Products => Set<Product>();

    protected override void OnModelCreating(ModelBuilder model) =>
        model.Entity<Product>().HasData(
            new Product { Id = 1, Name = "Coffee mug", Price = 12.00m },
            new Product { Id = 2, Name = "Tote bag", Price = 18.50m });
}
```

Replace `Program.cs` with the API:

```csharp Program.cs theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
using Microsoft.EntityFrameworkCore;
using Npgsql;

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;

builder.Services.AddDbContext<StoreDb>(options => options.UseNpgsql(connectionString));
builder.Services.AddHealthChecks().AddDbContextCheck<StoreDb>();

var app = builder.Build();

app.MapGet("/", (HttpRequest request) => $"Hello from ASP.NET Core on Sevalla over {request.Scheme}");
app.MapGet("/products", (StoreDb db) => db.Products.OrderBy(p => p.Id).ToListAsync());
app.MapHealthChecks("/healthz");

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.
* Without `GssEncryptionMode.Disable`, the logs show `Cannot load library libgssapi_krb5.so.2` when the application connects: Npgsql tries to load Kerberos, which Microsoft's runtime images don't include.
* `/` shows the scheme of the request, so you can check that the application sees HTTPS behind Sevalla's proxy.
* `/healthz` returns `Healthy` with status `200` when the database accepts a connection, and `Unhealthy` with `503` when it doesn't.

EF Core logs every SQL command at the `Information` level, so once the readiness probe calls `/healthz` every 10 seconds, its query fills the logs. Raise the level of EF Core's commands to `Warning` in `appsettings.json`:

```json appsettings.json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
{
  "Logging": {
    "LogLevel": {
      "Default": "Information",
      "Microsoft.AspNetCore": "Warning",
      "Microsoft.EntityFrameworkCore.Database.Command": "Warning"
    }
  },
  "AllowedHosts": "*"
}
```

Create the first migration, 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 InitialCreate
dotnet restore --use-lock-file
```

Run `dotnet run` and open the address it prints after `Now listening on:`. The page shows `Hello from ASP.NET Core on Sevalla over http`. `/products` and `/healthz` need a PostgreSQL database, which Sevalla provides in [Deploy to Sevalla](#deploy-to-sevalla).

## 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`. The other options are the ones Ingot uses itself: a Release build, and no native launcher, because the image starts the application with `dotnet`. 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 migrations 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 when the application starts, so Kestrel listens on all interfaces on the web process's port, `8080` by default. Don't set `urls`, `http_ports` or `Kestrel:Endpoints` in `appsettings.json`: they win over `ASPNETCORE_HTTP_PORTS`, and the build log warns about them.
* Sets `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true`. Sevalla's proxy ends HTTPS and passes the request on over HTTP with `X-Forwarded-Proto` and `X-Forwarded-For` headers; with this setting, ASP.NET Core takes the scheme and the client's address from them, so `Request.Scheme` is `https`, and HTTPS redirection, HSTS and sign-in callbacks work.
* Runs in the `Production` environment, because `ASPNETCORE_ENVIRONMENT` isn't set.

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

![The Create process sheet with Job selected, the Name and Custom start command fields, the Start policy set to Before deployment, and the H1 resource](https://assets.sevalla.com/screenshots/light/app-processes-job-create.png)

## 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`, the project, 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 ─╯
   ```

   Later, the build log shows the bundle being built (`Done. Migrations Bundle: /app/publish/efbundle`) and, during the rollout, `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**. 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 `Hello from ASP.NET Core on Sevalla over https`: the application sees the request's original scheme. Add `/products` to the address; it returns the two products the migration inserted:

   ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
   [{"id":1,"name":"Coffee mug","price":12.0},{"id":2,"name":"Tote bag","price":18.5}]
   ```

![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)

On the **Logs** tab, the `Migrate` process's first run shows `Failed executing DbCommand` for a query on `__EFMigrationsHistory`, then `Applying migration '<timestamp>_InitialCreate'` and `Done.`: EF Core looks for its history table before it creates it. Later runs show `No migrations were applied. The database is already up to date.`

If the deployment fails, read its build log, then see [Troubleshoot Ingot builds](https://docs.sevalla.com/applications/builds/ingot.md#troubleshoot-ingot-builds). If it deploys but the domain doesn't respond, read the application's [runtime logs](https://docs.sevalla.com/applications/logs.md).

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 request the endpoints:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
curl -s -w '\n' https://storefront-x7k2m.sevalla.app/
curl -s -w '\n' https://storefront-x7k2m.sevalla.app/healthz
```

```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
Hello from ASP.NET Core on Sevalla over https
Healthy
```

[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 '20261029185318_InitialCreate'.
Applying migration '20261029185318_InitialCreate'.
```

The migration's name starts with the time you created it, so yours differs.

## Turn on the readiness probe

Without a readiness probe, Sevalla sends traffic to a new instance as soon as its container starts. Point the probe at `/healthz`, so that during a deployment, the new version gets requests only once it runs and reaches the database:

**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 reaches **Deployed**, and `https://storefront-x7k2m.sevalla.app/healthz` returns `Healthy`. Health checks reach the instance by its IP address; `AllowedHosts` is `*`, so ASP.NET Core answers them. See [Health checks](https://docs.sevalla.com/applications/processes.md#health-checks) for every probe setting.

[Deploy with the API](#deploy-with-the-api) sets the same probe. [Get process](https://api-docs.sevalla.com/v3/applications/get-process) (`getProcessV3`) returns it in `readiness_probe`:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
curl -s https://api.sevalla.com/v3/applications/$APP_ID/processes/$WEB_ID \
  -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -c .readiness_probe
```

```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
{"httpGet":{"path":"/healthz","port":8080,"scheme":"HTTP"},"initialDelaySeconds":0,"periodSeconds":10,"timeoutSeconds":1,"successThreshold":1,"failureThreshold":3}
```

## 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 ./
RUN dotnet restore --locked-mode && 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 publishes no Debian images for .NET 10, and its 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, 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:UseAppHost=false` | No native launcher: the image starts the application with `dotnet`. |
| `ASPNETCORE_FORWARDEDHEADERS_ENABLED=true` | The same setting as Ingot's: `Request.Scheme` is `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. |
| `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 finishes the requests in progress, 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
Dockerfile
.dockerignore
```

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 9 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 job runs `/app/efbundle` from the new image. The domain shows `Hello from ASP.NET Core on Sevalla over https` and `/products` returns the same two products. 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 instances. For a schema change, run `dotnet ef migrations add <Name>` locally and commit the new files in `Migrations/` with the code. 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"]`, and write a nested setting such as `ConnectionStrings:Default` as `ConnectionStrings__Default`, with two underscores. A variable the application reads only while it runs needs **Available during runtime**. 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. `AllowedHosts` is `*`, 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 |
| - | - | - |
| The deployment fails at `Migrate has failed` | The bundle can't reach the database, or a migration raised an error. | On the **Logs** tab, choose the `Migrate` process to read its output. Check that the internal connection exists and that the `DB_*` variables are set. |
| 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`. |
| The build log warns `appsettings.json sets the addresses ASP.NET Core listens on, which take precedence over ASPNETCORE_HTTP_PORTS, so the application ignores PORT` | `urls`, `http_ports` or `Kestrel:Endpoints` in the settings win over the port Sevalla sets. | Remove them from `appsettings.json` and `appsettings.Production.json`. |
| `/` shows `over http` | `ASPNETCORE_FORWARDEDHEADERS_ENABLED` isn't set, which happens with a Dockerfile that doesn't set it. | Add `ENV ASPNETCORE_FORWARDEDHEADERS_ENABLED=true` to the final stage. |

For more causes, see [Troubleshoot Ingot builds](https://docs.sevalla.com/applications/builds/ingot.md#troubleshoot-ingot-builds). To add an interactive web interface, see [Deploy a Blazor application](https://docs.sevalla.com/guides/dotnet/blazor.md).

## Deploy with the API

These calls make the same deployment as [Deploy to Sevalla](#deploy-to-sevalla) and [Turn on the readiness probe](#turn-on-the-readiness-probe), 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 and the readiness probe**

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 and adds the readiness probe from [Turn on the readiness probe](#turn-on-the-readiness-probe), with the dashboard's default timings. Send `timeoutSeconds`: a probe without it gets 120 seconds, where the dashboard sets 1.

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

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.

**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 products, which the job inserted, from the application's domain:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
curl -s -w '\n' https://$HOST/products
```

```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
[{"id":1,"name":"Coffee mug","price":12.0},{"id":2,"name":"Tote bag","price":18.5}]
```

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.