> ## 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 Django application

> Deploy a Django 6.1 project to Sevalla with Ingot or your own Dockerfile: Gunicorn serves it, WhiteNoise serves static files, and a job migrates PostgreSQL.

A Django project runs on Sevalla as an application built from your Git repository: [Ingot](https://docs.sevalla.com/applications/builds/ingot.md) installs its dependencies, collects its static files during the build and starts it with Gunicorn in the web process, WhiteNoise serves the static files, and a job runs the migrations before each deployment. Its data lives in a Sevalla PostgreSQL database that the application reaches over an internal connection.

## At a glance

| | |
| - | - |
| Source | A Git repository |
| Build | [Ingot](https://docs.sevalla.com/applications/builds/ingot.md) (Python 3.14, pip), or the [Dockerfile](#deploy-with-a-dockerfile) |
| Start command | `gunicorn -c /etc/ingot/gunicorn.conf.py storefront.wsgi:application`, which Ingot detects from Django and Gunicorn |
| Port | The `PORT` environment variable, `8080` by default |
| Processes | Web process; `Migrate` job (`python manage.py migrate --noinput`, **Before deployment**) |
| Services | PostgreSQL 18 over an internal connection |
| Disk | None |
| Health check | None configured. [Add Django health checks](https://docs.sevalla.com/guides/python/django/health-checks.md) adds them |
| Size | **H1** for the web process and the job, **DB1** for the database |

### Environment variables

| Variable | Required | Available during | Secret | Value |
| - | - | - | - | - |
| `DB_URL` | Yes | Build and runtime | Yes | Added by the internal connection to `orders-db`: `postgres://<user>:<password>@<host>:<port>/<database>` |
| `SECRET_KEY` | Yes | Runtime | Yes | 50 or more random characters. Generate with `python3 -c "import secrets; print(secrets.token_urlsafe(50))"` |
| `ALLOWED_HOSTS` | Yes | Runtime | No | The application's domain, such as `storefront-x7k2m.sevalla.app`. Separate several hosts with commas |
| `DEBUG` | No | Runtime | No | Don't set it: `False` by default |
| `WEB_CONCURRENCY` | No | Runtime | No | Gunicorn worker processes, `1` by default. Raise it on sizes larger than **H1** |
| `PORT` | No | Runtime | No | Set by Sevalla to the web process port |

The internal connection also adds `DB_HOST`, `DB_PORT`, `DB_DATABASE`, `DB_USERNAME` and `DB_PASSWORD`, which the project doesn't read.

## 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).
* Python 3.12 or later on your computer. Django 6.1 needs Python 3.12 or later.

## Create the project

Create a virtual environment, install Django and the packages the project needs in production, and start a project named `storefront`:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
mkdir storefront && cd storefront
python3 -m venv .venv
source .venv/bin/activate
pip install django django-environ gunicorn whitenoise "psycopg[binary]"
django-admin startproject storefront .
```

| Package | What it does |
| - | - |
| `django` | Django 6.1 |
| `django-environ` | Reads settings from environment variables and database URLs |
| `gunicorn` | Production WSGI server. Ingot starts the web process with it when it's installed. |
| `whitenoise` | Serves static files from the application |
| `psycopg[binary]` | PostgreSQL driver, with its own copy of the PostgreSQL client library |

Keep local files out of the repository:

```text .gitignore theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
.venv/
__pycache__/
.env
db.sqlite3
staticfiles/
```

For local development, put development values in `.env`. Sevalla doesn't use this file: you set the production values as environment variables.

```bash .env theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
DEBUG=True
SECRET_KEY=local-development-only
```

## Prepare the project for Sevalla

### Read settings from environment variables

In `storefront/settings.py`, replace everything from `from pathlib import Path` to `ALLOWED_HOSTS = []` so that the secret key, debug mode and hosts come from the environment:

```python storefront/settings.py theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
from pathlib import Path

import environ

BASE_DIR = Path(__file__).resolve().parent.parent

env = environ.Env()
environ.Env.read_env(BASE_DIR / ".env")

SECRET_KEY = env("SECRET_KEY")
DEBUG = env.bool("DEBUG", default=False)
ALLOWED_HOSTS = env.list("ALLOWED_HOSTS", default=["localhost", "127.0.0.1"])
```

Then replace the `DATABASES` setting:

```python storefront/settings.py theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
DATABASES = {
    "default": env.db("DB_URL", default="sqlite:///db.sqlite3"),
}
```

* `DEBUG` is `False` unless you set it.
* `DB_URL` is the variable Sevalla adds when you connect the database. django-environ accepts the `postgres://` URL that Sevalla generates. Without `DB_URL`, the project uses SQLite locally.
* Django sees HTTPS requests as secure without `SECURE_PROXY_SSL_HEADER`: Ingot's image trusts the `X-Forwarded-Proto` header that Sevalla's proxy sets (see [proxy headers](https://docs.sevalla.com/guides/python/overview.md#how-python-applications-run-on-sevalla)). Form posts on the application's own domains, such as the admin's sign-in, pass Django's CSRF check without `CSRF_TRUSTED_ORIGINS`.

### Serve static files with WhiteNoise

Add WhiteNoise right after `SecurityMiddleware`:

```python storefront/settings.py theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
MIDDLEWARE = [
    "django.middleware.security.SecurityMiddleware",
    "whitenoise.middleware.WhiteNoiseMiddleware",
    "django.contrib.sessions.middleware.SessionMiddleware",
    # ...the rest of the default middleware...
]
```

Then replace `STATIC_URL` with where Django collects static files and how it stores them:

```python storefront/settings.py theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
STATIC_URL = "static/"
STATIC_ROOT = BASE_DIR / "staticfiles"

STORAGES = {
    "default": {"BACKEND": "django.core.files.storage.FileSystemStorage"},
    "staticfiles": {"BACKEND": "whitenoise.storage.CompressedManifestStaticFilesStorage"},
}
```

Because the settings set `STATIC_ROOT`, Ingot runs `python manage.py collectstatic --noinput` during the build, so the files are part of the image. WhiteNoise compresses them and gives them hashed names, so browsers and the [Sevalla CDN](https://docs.sevalla.com/applications/caching.md) can cache them for a long time.

### Pin the Python version

Ingot builds on Python 3.14, its default line, unless the project sets a version. Django 6.1 supports Python 3.12 to 3.14. Pin 3.14 in `.python-version`, so the build doesn't change when a new Ingot release moves its default line:

```text .python-version theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
3.14
```

See [Pin the Python version](https://docs.sevalla.com/guides/python/overview.md#pin-the-python-version).

### List the dependencies

Ingot installs `requirements.txt` with pip, into a virtual environment at `/app/.venv` that's on the `PATH`:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
pip freeze > requirements.txt
```

### How Ingot builds and starts the project

The project needs no build or start configuration. Ingot finds `manage.py` and Django in `requirements.txt`, and then:

* Installs the dependencies and runs `collectstatic`. If `SECRET_KEY` isn't available during the build, Ingot sets a placeholder for `collectstatic` only, which doesn't use it.
* Starts the web process with `gunicorn -c /etc/ingot/gunicorn.conf.py storefront.wsgi:application`. Gunicorn listens on the port in the `PORT` environment variable, which Sevalla sets to the web process's port (`8080` by default).
* Doesn't run migrations. A [job](https://docs.sevalla.com/applications/processes.md#jobs) runs them once per deployment, before the new version starts.

Gunicorn runs 1 worker process, and Ingot's Gunicorn settings give it 4 threads, which fits the smallest size, **H1** (0.3 GB of memory). On a larger size, set the `WEB_CONCURRENCY` environment variable to the number of worker processes, for example `2`: Gunicorn reads it at start. To run another server or other options, see [Set the start command](https://docs.sevalla.com/applications/builds/ingot.md#set-the-start-command).

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_URL` and the other connection variables to the application. See [Connect an application](https://docs.sevalla.com/databases/connect.md#connect-an-application).

**4. Add the environment variables**

Click the **Environment variables** tab, then click **Add environment variables**. Add these variables and click **Add environment variables**:

| Variable | Value |
| - | - |
| `SECRET_KEY` | A random string of 50 characters or more. Generate one with `python3 -c "import secrets; print(secrets.token_urlsafe(50))"`. |
| `ALLOWED_HOSTS` | The application's domain without the scheme, for example `storefront-x7k2m.sevalla.app`. It's under the application's name in the page header. Separate several hosts with commas. |

Don't set `DEBUG`: it defaults to `False`.

**5. Create the migration job**

Click the **Processes** tab, then click **Create process**. Choose **Job**, enter `Migrate` as the **Name** and `python manage.py migrate --noinput` as the **Custom start command**. Keep the **Start policy** at **Before deployment** and the **Resource** at **H1**, then click **Create process**.

**6. Deploy**

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

**7. 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, wait for the deployment's status to change to **Deployed**. The application's status next to its name changes to **Running**. Open the deployment to read its build log. Ingot's build plan comes first:

   ```text Build log theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
   ╭─ ■ Django · Python 3.14 ─────────────────────────────────────────────────────────────────────────────────────╮
   │ Python           3.14                                                                 .python-version "3.14" │
   │ Package manager  pip                                                                  requirements.txt       │
   │ Framework        Django                                                               manage.py              │
   │ Start            gunicorn -c /etc/ingot/gunicorn.conf.py storefront.wsgi:application  Django                 │
   ├─ Image ──────────────────────────────────────────────────────────────────────────────────────────────────────┤
   │ Build            python:3.14-slim-trixie                                                                     │
   │ Runtime          python:3.14-slim-trixie                                                                     │
   │ User             1000:1000                                                                                   │
   │ Init             tini                                                                                        │
   │ Port             $PORT, default 8080                                                                         │
   ╰─────────────────────────────────────────────────────────────────────────────────────────────── Ingot v0.5.0 ─╯
   ```

   Later, the build log shows `collectstatic` copying the static files to `/app/staticfiles`, and, during the rollout, `Migrate has been successful`. If the job fails, the deployment fails and nothing changes for visitors. See [Read the build plan](https://docs.sevalla.com/applications/builds/ingot.md#read-the-build-plan).

   With the API, [Get deployment](https://api-docs.sevalla.com/v3/applications/get-deployment) (`getDeploymentV3`) returns the status, `success` for **Deployed**, and [Get application deployment logs](https://api-docs.sevalla.com/v3/applications/get-application-deployment-logs) (`getApplicationDeploymentLogsV3`) returns the build log, which `search` filters. `APP_ID` and `DEPLOYMENT_ID` come from [Deploy with the API](#deploy-with-the-api):

   ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
   curl -s "$API/applications/$APP_ID/deployments/$DEPLOYMENT_ID" -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r .status
   curl -s "$API/applications/$APP_ID/deployments/$DEPLOYMENT_ID/logs?search=Migrate%20has%20been%20successful" \
     -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.[].message'
   ```

   ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
   success
   ✅ Migrate has been successful
   ```
2. Click the domain under the application's name, then add `/admin/` to the address. Django's admin sign-in page opens with its styles, which shows that WhiteNoise serves the static files. The site root returns `404` until you add your own URLs, because the welcome page only shows with `DEBUG` on. From a shell, with your application's domain:

   ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
   curl -s https://storefront-x7k2m.sevalla.app/admin/login/ | grep -o '<title>.*</title>'
   curl -s -o /dev/null -w '%{http_code} %{content_type}\n' https://storefront-x7k2m.sevalla.app/static/admin/css/base.css
   curl -s -o /dev/null -w '%{http_code}\n' https://storefront-x7k2m.sevalla.app/
   ```

   ```text theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
   <title>Log in | Django site admin</title>
   200 text/css; charset="utf-8"
   404
   ```
3. To sign in to the admin, create a superuser. Click the **Web terminal** tab, and in the shell that opens in the **Web** process, run:

   ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
   python manage.py createsuperuser
   ```

   Ingot puts the virtual environment's `bin` folder on the `PATH`, so `python` is the project's Python with its packages. See [Web terminal](https://docs.sevalla.com/applications/web-terminal.md).

   `createsuperuser` asks for a password, so it needs the terminal. A script or an AI agent can run a command that doesn't ask anything with [Run a command in a process](https://api-docs.sevalla.com/v3/applications/run-a-command-in-a-process) (`execProcessCommandV3`). `migrate --check` exits with `0` when every migration has run:

   ```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
   curl -s -X POST "$API/applications/$APP_ID/processes/$WEB_ID/exec" \
     -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
     -d '{"command": ["python", "manage.py", "migrate", "--check"]}'
   ```

   ```json theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
   {"stdout":"","stderr":"","exit_code":0}
   ```

   CLI: `sevalla apps processes exec "$WEB_ID" --app-id "$APP_ID" -- python manage.py migrate --check`. MCP: `sevalla_api_update` with `execProcessCommandV3`.

## Deploy with a Dockerfile

Ingot needs no Dockerfile. Write your own when you want full control of the image: the base image, the system packages and every layer. 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 python:3.14-slim-trixie

ENV PYTHONUNBUFFERED=1 \
    PORT=8080 \
    FORWARDED_ALLOW_IPS="*"

RUN useradd --uid 1000 --create-home app
WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir --root-user-action=ignore -r requirements.txt

COPY . .
RUN SECRET_KEY=collectstatic-placeholder python manage.py collectstatic --noinput \
    && python -m compileall -q .

USER 1000:1000
EXPOSE 8080
CMD ["gunicorn", "storefront.wsgi:application", \
     "--threads", "4", "--keep-alive", "0", \
     "--graceful-timeout", "20", "--worker-tmp-dir", "/dev/shm"]
```

| Line or choice | Why |
| - | - |
| `python:3.14-slim-trixie` | The Python line that `.python-version` pins, on Debian 13, as Ingot builds it. A line tag picks up each patch release and security fix when you deploy again; a digest would stay on one release. |
| One stage | pip installs prebuilt wheels, so the build needs no compiler, and `collectstatic` writes files that the image serves. |
| `requirements.txt` before the code | Docker reuses the installed packages until `requirements.txt` changes, so a code change rebuilds only the last layers. |
| `pip install` into the image's Python | The image runs one application, so it needs no virtual environment. `--root-user-action=ignore` silences pip's warning about installing as root. |
| `SECRET_KEY=collectstatic-placeholder` | The settings need a secret key to load, and `collectstatic` doesn't use it. The real `SECRET_KEY` is set only when the application runs, so it never enters the image. |
| `compileall` | Compiles the code at build time, because the application can't write to `/app` when it runs. |
| `useradd` and `USER 1000:1000` | Runs Gunicorn as an unprivileged user with a home directory, where Gunicorn keeps its control socket. The code stays owned by root, so the application can't change it. |
| `FORWARDED_ALLOW_IPS="*"` | Gunicorn trusts the `X-Forwarded-Proto` header from Sevalla's proxy, so Django sees HTTPS requests as secure and the admin's sign-in passes the CSRF check. Ingot sets the same. |
| Gunicorn options | Gunicorn listens on `0.0.0.0` and the port in `PORT` on its own, and reads `WEB_CONCURRENCY`. `--threads 4`, `--graceful-timeout 20` and `--worker-tmp-dir /dev/shm` match Ingot's settings. `--keep-alive 0` closes each connection after its response: otherwise Gunicorn 26.2 waits out the whole graceful timeout before it stops when the proxy holds an idle connection open. |
| No init process | Gunicorn runs as PID 1, handles `SIGTERM` itself, finishes the requests in progress and exits. |

```text .dockerignore theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
.git
.venv
**/__pycache__
.env*
db.sqlite3
staticfiles
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 an **Ignored** row with `8 patterns from .dockerignore`. 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 Update build strategy sheet with Dockerfile selected, the Dockerfile path, the Docker context and the Docker registry credential](https://assets.sevalla.com/screenshots/light/app-settings-build-strategy-dockerfile.png)

The build log shows `📦 Building and pushing docker image using Dockerfile...` where Ingot's build plan was, then `Migrate has been successful`: the job runs `python manage.py migrate --noinput` in the new image. The admin at `/admin/` opens with its styles, signing in works as before, and the deployment's **Dockerfile** tab shows your Dockerfile. See [Dockerfile](https://docs.sevalla.com/applications/builds/dockerfile.md).

## 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 `python manage.py makemigrations` locally and commit the new migration with the code. When you add a package, run `pip freeze > requirements.txt` again and commit it. See [Deployments](https://docs.sevalla.com/applications/deployments.md).

## Add a custom domain

[Add the domain](https://docs.sevalla.com/domains/overview.md) on the application's **Domains** tab, then add it to `ALLOWED_HOSTS`, for example `storefront-x7k2m.sevalla.app,shop.example.com`, and deploy. Custom domains need a web process larger than **H1**.

## Troubleshoot the deployment

| Symptom | Cause | Fix |
| - | - | - |
| Every page returns `Bad Request (400)` | The domain isn't in `ALLOWED_HOSTS`. With `DEBUG` off, Django doesn't log the rejected host. | Add the domain to `ALLOWED_HOSTS`, then deploy. |
| The deployment fails at `Migrate has failed` | The migration raised an error, or the application can't reach the database. | On the **Logs** tab, choose the `Migrate` process to read its output. Check that the internal connection exists and that `DB_URL` is set. |
| The job's output or the web process's runtime logs show `Set the SECRET_KEY environment variable` | `SECRET_KEY` isn't set, or isn't **Available during runtime**. | Add or update the variable, then deploy. |
| The admin has no styles | `STATIC_ROOT` isn't set, so Ingot doesn't run `collectstatic`, or WhiteNoise isn't in `MIDDLEWARE`. | Check both settings. The build log shows the `collectstatic` step when `STATIC_ROOT` is set. |
| The build log warns `Nothing serves the files collectstatic puts in STATIC_ROOT` | `whitenoise` isn't in `requirements.txt`. | Install WhiteNoise, run `pip freeze > requirements.txt`, and commit the change. |
| With your own Dockerfile, signing in to the admin fails with `CSRF verification failed. Request aborted.` | Gunicorn doesn't trust the `X-Forwarded-Proto` header from Sevalla's proxy, so Django sees the HTTPS form post as HTTP and rejects its origin. | Set `FORWARDED_ALLOW_IPS="*"` in the Dockerfile, as in [Deploy with a Dockerfile](#deploy-with-a-dockerfile). |

For more causes, see [Troubleshoot Ingot builds](https://docs.sevalla.com/applications/builds/ingot.md#troubleshoot-ingot-builds) and [Troubleshoot builds and deployments](https://docs.sevalla.com/applications/troubleshooting/builds-and-deployments.md). To add uploads, caching or background tasks, see the [Django guides](https://docs.sevalla.com/guides/python/django/overview.md).

## Deploy with the API

This sequence creates the same database, application, job and deployment as [Deploy to Sevalla](#deploy-to-sevalla), with the [Sevalla API](https://docs.sevalla.com/developer-tools/api.md), and builds with Ingot. A script or an AI agent runs it as is. Run the steps in order in one shell: later steps use the IDs that earlier steps save in shell variables. Each step names the [CLI](https://docs.sevalla.com/developer-tools/cli.md) command and the [Sevalla 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, in `SEVALLA_API_KEY`.
* The repository pushed as in [Prepare the project for Sevalla](#prepare-the-project-for-sevalla), and a GitHub account with access to it connected to Sevalla. The API has no call that reports the connection: without access, the step that creates the application fails with `400` and `Cannot access repository https://github.com/acme/storefront: Repository not found or you don't have access.`, followed by where to connect a Git account (**My account** in the dashboard) and, for GitHub, to give Sevalla's GitHub App access to the repository.
* `curl`, `jq`, `openssl` and `python3`.

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
API=https://api.sevalla.com/v3
REPO=https://github.com/acme/storefront
BRANCH=main
```

**1. Choose the location**

[List clusters](https://api-docs.sevalla.com/v3/resources/list-clusters) (`listClustersV3`) returns every location with its `display_name` and its region ID in `location`. Save one by region ID (see [Locations](https://docs.sevalla.com/platform/locations.md)):

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
CLUSTER_ID=$(curl -s "$API/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. Look up the process size**

[List process resource types](https://api-docs.sevalla.com/v3/resources/list-process-resource-types) (`listProcessResourceTypesV3`) returns the sizes by `name`. Save **H1**:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
H1_ID=$(curl -s "$API/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`.

**3. Look up the database size**

[List database resource types](https://api-docs.sevalla.com/v3/resources/list-database-resource-types) (`listDatabaseResourceTypesV3`). Save the smallest size, **DB1**:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
DB1_ID=$(curl -s "$API/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. Look up the PostgreSQL version**

[List database versions](https://api-docs.sevalla.com/v3/resources/list-database-versions) (`listDatabaseVersionsV3`) returns the versions the location offers, oldest first. Save the newest:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
PG_VERSION=$(curl -s "$API/resources/database-versions?cluster_id=$CLUSTER_ID&type=postgresql" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.[0].versions[-1]')
```

CLI: `sevalla resources db-versions --cluster "$CLUSTER_ID" --type postgresql`. MCP: not needed, `create_database` takes the newest version by default.

**5. Create the database**

[Create database](https://api-docs.sevalla.com/v3/databases/create-database) (`createDatabaseV3`) starts creating the database and returns its ID. You choose the password, and the API never returns it, so keep it for the connection URL:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
DB_PASSWORD=$(openssl rand -hex 16)
DB_ID=$(curl -s -X POST "$API/databases" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg cluster "$CLUSTER_ID" --arg size "$DB1_ID" --arg version "$PG_VERSION" --arg password "$DB_PASSWORD" \
    '{display_name: "orders-db", type: "postgresql", version: $version, cluster_id: $cluster,
      resource_type_id: $size, db_name: "storefront", db_user: "storefront", db_password: $password}')" \
  | jq -r .id)
```

CLI: `sevalla databases create --name orders-db --type postgresql --db-version "$PG_VERSION" --cluster "$CLUSTER_ID" --resource-type "$DB1_ID" --db-name storefront --db-user storefront --db-password "$DB_PASSWORD"`. MCP: `create_database`, which generates a password it never returns. With `connect_to_application_id` and `env_var_name: "DB_URL"`, once the application exists, it also does the internal connection and adds `DB_URL` as a `postgresql://` URL, which django-environ accepts too.

**6. Wait for the database**

[Get database](https://api-docs.sevalla.com/v3/databases/get-database) (`getDatabaseV3`) shows `status` `ready` when the database is up, with its internal hostname and port:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
for i in $(seq 1 60); do
  [ "$(curl -s "$API/databases/$DB_ID" -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.status // empty')" = ready ] && break
  sleep 10
done
DB=$(curl -s "$API/databases/$DB_ID" -H "Authorization: Bearer $SEVALLA_API_KEY")
DB_HOST=$(echo "$DB" | jq -r .internal_hostname)
DB_PORT=$(echo "$DB" | jq -r .internal_port)
```

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

**7. Create the application**

[Create application](https://api-docs.sevalla.com/v3/applications/create-application) (`createApplicationV3`) creates the application with a web process, and doesn't deploy it:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
APP_ID=$(curl -s -X POST "$API/applications" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg cluster "$CLUSTER_ID" --arg repo "$REPO" --arg branch "$BRANCH" \
    '{display_name: "storefront", cluster_id: $cluster, source: "privateGit", git_type: "github",
      repo_url: $repo, default_branch: $branch}')" \
  | jq -r .id)
```

CLI: `sevalla apps create --name storefront --cluster "$CLUSTER_ID" --source privateGit --git-type github --repository "$REPO" --branch "$BRANCH"`. MCP: `create_application` with `deploy: false`.

**8. Find the web process**

[List processes](https://api-docs.sevalla.com/v3/applications/list-processes) (`listProcessesV3`) returns the web process the application came with:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
WEB_ID=$(curl -s "$API/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`.

**9. Size the web process**

The API creates the web process at **S1**, not the dashboard's **H1**. [Update process](https://api-docs.sevalla.com/v3/applications/update-process) (`updateProcessV3`) sets **H1**:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
curl -s -X PATCH "$API/applications/$APP_ID/processes/$WEB_ID" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg size "$H1_ID" '{resource_type_id: $size}')" | jq -r .resource_type_name
```

It prints `h1`. CLI: `sevalla apps processes update "$WEB_ID" --app-id "$APP_ID" --resource-type "$H1_ID"`. MCP: `scale_process` with `size_id` and `apply_now: false`.

**10. Connect the database**

[Create internal connection](https://api-docs.sevalla.com/v3/applications/create-internal-connection) (`createApplicationInternalConnectionV3`):

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
curl -s -X POST "$API/applications/$APP_ID/internal-connections" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg db "$DB_ID" '{target_id: $db, target_type: "database"}')" | jq -r .id
```

Unlike the dashboard, the API adds no environment variables; the next steps add them. CLI: `sevalla apps internal-connections create "$APP_ID" --target-id "$DB_ID" --target-type database`. MCP: `sevalla_api_create` with `createApplicationInternalConnectionV3` and the same body.

**11. Get the domain**

[List application domains](https://api-docs.sevalla.com/v3/applications/list-application-domains) (`listApplicationDomainsV3`) returns the application's `sevalla.app` domain, which `ALLOWED_HOSTS` needs:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
APP_HOST=$(curl -s "$API/applications/$APP_ID/domains" -H "Authorization: Bearer $SEVALLA_API_KEY" \
  | jq -r '.data[] | select(.is_primary) | .name')
```

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

**12. Add the environment variables**

[Create environment variable](https://api-docs.sevalla.com/v3/applications/create-environment-variable) (`createEnvironmentVariableV3`), once per variable. The `DB_*` variables have the names and format of the dashboard's internal connection, available during build and runtime as it adds them. `SECRET_KEY` and `ALLOWED_HOSTS` are available during runtime only:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
SECRET_KEY=$(python3 -c "import secrets; print(secrets.token_urlsafe(50))")
add_var() {
  curl -s -X POST "$API/applications/$APP_ID/env-vars" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
    -d "$(jq -n --arg key "$1" --arg value "$2" --argjson build "$3" \
      '{key: $key, value: $value, is_runtime: true, is_buildtime: $build}')" | jq -r .key
}
add_var DB_HOST "$DB_HOST" true
add_var DB_PORT "$DB_PORT" true
add_var DB_DATABASE storefront true
add_var DB_USERNAME storefront true
add_var DB_PASSWORD "$DB_PASSWORD" true
add_var DB_URL "postgres://storefront:$DB_PASSWORD@$DB_HOST:$DB_PORT/storefront" true
add_var SECRET_KEY "$SECRET_KEY" false
add_var ALLOWED_HOSTS "$APP_HOST" false
```

It prints each key as it's added. CLI: `sevalla apps env-vars create "$APP_ID" --key SECRET_KEY --value "$SECRET_KEY"`, once per variable; the CLI makes each variable available during build and runtime. MCP: `set_environment_variables`, with `buildtime: false` for `SECRET_KEY` and `ALLOWED_HOSTS`.

**13. Create the migration job**

[Create process](https://api-docs.sevalla.com/v3/applications/create-process) (`createProcessV3`) needs the size, a `scaling_strategy` and, for a job, the `job_start_policy`:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
curl -s -X POST "$API/applications/$APP_ID/processes" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d "$(jq -n --arg size "$H1_ID" '{display_name: "Migrate", type: "job", entrypoint: "python manage.py migrate --noinput",
    resource_type_id: $size, job_start_policy: "beforeDeployment", scaling_strategy: {type: "manual", config: {instanceCount: 1}}}')" \
  | jq -r .id
```

CLI: `sevalla apps processes create "$APP_ID" --name Migrate --type job --resource-type "$H1_ID" --command "python manage.py migrate --noinput" --job-start-policy beforeDeployment`. MCP: `sevalla_api_create` with `createProcessV3` and the same body.

**14. Deploy**

[Trigger deployment](https://api-docs.sevalla.com/v3/applications/trigger-deployment) (`triggerDeploymentV3`) deploys the latest commit of the branch:

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
DEPLOYMENT_ID=$(curl -s -X POST "$API/applications/$APP_ID/deployments" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" -d '{}' | jq -r .id)
```

CLI: `sevalla apps deployments trigger "$APP_ID"`. MCP: `trigger_deployment`.

**15. Wait for the deployment**

[Get deployment](https://api-docs.sevalla.com/v3/applications/get-deployment) (`getDeploymentV3`) reports the `status`, which ends as `success`, `failed`, `cancelled` or `skipped`. The loop keeps polling through a failed request, 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 "$API/applications/$APP_ID/deployments/$DEPLOYMENT_ID" \
    -H "Authorization: Bearer $SEVALLA_API_KEY" | jq -r '.status // empty')
  case $STATUS in success|failed|cancelled|skipped) break ;; esac
  sleep 15
done
echo "$STATUS"
```

CLI: `sevalla apps deployments get "$DEPLOYMENT_ID" --app-id "$APP_ID"`. MCP: `get_deployment`.

**16. Turn on auto-deploy**

[Update application](https://api-docs.sevalla.com/v3/applications/update-application) (`updateApplicationV3`):

```bash theme={"theme":{"light":"github-dark-default","dark":"github-dark-default"}}
curl -s -X PATCH "$API/applications/$APP_ID" \
  -H "Authorization: Bearer $SEVALLA_API_KEY" -H "Content-Type: application/json" \
  -d '{"auto_deploy": true}' | jq -r .auto_deploy
```

It prints `true`. CLI: `sevalla apps update "$APP_ID" --data '{"auto_deploy": true}'`. MCP: `sevalla_api_update` with `updateApplicationV3` and the same body.

Then run the checks in [Verify the deployment](#verify-the-deployment), with `APP_HOST` in place of `storefront-x7k2m.sevalla.app`. To build with the [Dockerfile](#deploy-with-a-dockerfile) instead, update the application with `{"build_type": "dockerfile", "dockerfile_path": "Dockerfile", "docker_context": "."}` before you deploy (CLI: `sevalla apps update "$APP_ID" --data` with the same body; its `--build-type` option leaves the Docker context unset).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.