Deploy FastAPI - Sevalla docs

A FastAPI project runs on Sevalla as an application built from your Git repository: Nixpacks installs it, fastapi run serves it with Uvicorn in the web process, and a job runs its Alembic migrations before each deployment. Its data lives in a Sevalla PostgreSQL database that the application reaches over an internal connection.

Before you begin

A Sevalla company with a payment method, and a GitHub, GitLab or Bitbucket account for the repository. See Git providers.
Python 3.12 or later on your computer.

Create the project

Create a virtual environment and install FastAPI, SQLModel, Alembic and the PostgreSQL driver:

mkdir storefront && cd storefront
python3 -m venv .venv
source .venv/bin/activate
pip install "fastapi[standard]" sqlmodel alembic "psycopg[binary]"
mkdir storefront && touch storefront/__init__.py

Package	What it does
`fastapi[standard]`	FastAPI with the `fastapi` command, Uvicorn and form and file upload support
`sqlmodel`	Models and sessions on top of SQLAlchemy
`alembic`	Database migrations
`psycopg[binary]`	PostgreSQL driver

Keep local files out of the repository:

.gitignore

.venv/
__pycache__/
.env
*.db

Add the database engine. Sevalla’s connection URLs start with postgres://, which SQLAlchemy doesn’t accept, so the code switches the scheme to postgresql+psycopg://:

storefront/db.py

import os
from typing import Annotated

from fastapi import Depends
from sqlmodel import Session, create_engine

def database_url() -> str:
    url = os.environ.get("DB_URL", "sqlite:///storefront.db")
    return url.replace("postgres://", "postgresql+psycopg://", 1)

engine = create_engine(database_url())

def get_session():
    with Session(engine) as session:
        yield session

SessionDep = Annotated[Session, Depends(get_session)]

DB_URL is the variable Sevalla adds when you connect the database; without it, the project uses SQLite locally. Add a model and the application:

storefront/models.py

from sqlmodel import Field, SQLModel


class Item(SQLModel, table=True):
    id: int | None = Field(default=None, primary_key=True)
    name: str

storefront/main.py

from fastapi import FastAPI
from sqlmodel import select

from storefront.db import SessionDep
from storefront.models import Item

app = FastAPI()


@app.get("/")
def index(session: SessionDep):
    items = session.exec(select(Item)).all()
    return {"items": len(items)}


@app.post("/items")
def create_item(item: Item, session: SessionDep) -> Item:
    session.add(item)
    session.commit()
    session.refresh(item)
    return item

Prepare the project for Sevalla

Set up migrations

Create the Alembic files:

alembic init alembic

In alembic/env.py, point Alembic at the same database URL and at the SQLModel tables. Replace the config and target_metadata lines:

alembic/env.py

from sqlmodel import SQLModel

import storefront.models  # noqa: F401 (registers the tables)
from storefront.db import database_url

config = context.config
# Alembic's config treats % as a special character: passwords in URLs can contain it.
config.set_main_option("sqlalchemy.url", database_url().replace("%", "%%"))

target_metadata = SQLModel.metadata

SQLModel columns use its own types, so add the import to the template that Alembic writes migrations from:

alembic/script.py.mako

from alembic import op
import sqlalchemy as sa
import sqlmodel

Generate the first migration and apply it to the local database:

alembic revision --autogenerate -m "Create item table"
alembic upgrade head
fastapi dev storefront/main.py

Pin the Python version

Nixpacks, the default build strategy, reads the Python version from .python-version. Nixpacks 1.41 supports Python versions up to 3.13, so pin 3.13:

.python-version

3.13

Set the start command

Create nixpacks.toml in the repository root:

nixpacks.toml

[start]
cmd = "fastapi run storefront/main.py --port $PORT --forwarded-allow-ips '*'"

fastapi run starts Uvicorn in production mode on 0.0.0.0. Requests reach it through Sevalla’s ingress, so --forwarded-allow-ips '*' makes Uvicorn trust the X-Forwarded-Proto and X-Forwarded-For headers, and FastAPI sees the original scheme and client address. See Request headers.
The web process listens on the port in the PORT environment variable. Sevalla sets PORT to the web process’s port, 8080 by default.
To use more CPU, add --workers 2 (or more) when you choose a larger size.
Migrations don’t run here. A job runs them once per deployment.

List the dependencies

Nixpacks installs requirements.txt with pip:

pip freeze > requirements.txt

Commit everything, including the alembic folder and alembic.ini, and push it to your Git provider:

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

Deploy to Sevalla

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 for every field.

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.

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.

Create the migration job

Click the Processes tab, then click Create process. Choose Job, enter Migrate as the Name and alembic upgrade head as the Custom start command. Keep the Start policy at Before deployment and the Resource at H1, then click Create process.

Deploy

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

Turn on auto-deploy

To deploy every push to the branch automatically, click the Settings tab, then click Update auto-deploy in the Auto-deploy section. Turn on Auto-deploy and click Update auto-deploy. See Deployments.

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

Verify the deployment

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. During the rollout, the deployment’s build log shows Migrate has been successful. If the job fails, the deployment fails and nothing changes for visitors.
Click the domain under the application’s name. The response is {"items":0}, which shows that the application reads the PostgreSQL database.

Add an item and read it back, with your application’s domain:

curl -X POST https://storefront-x7k2m.sevalla.app/items \
  -H "Content-Type: application/json" \
  -d '{"name": "Mug"}'
curl https://storefront-x7k2m.sevalla.app/

The second response is {"items":1}. The interactive API docs are at /docs.

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 alembic revision --autogenerate locally and commit the new migration with the code. See Deployments.

Add a custom domain

Add the domain on the application’s Domains tab. FastAPI doesn’t check the host, so no code change is needed. Custom domains need a web process larger than H1.

Troubleshoot the deployment

Symptom	Cause	Fix
The application or the job crashes with `Can't load plugin: sqlalchemy.dialects:postgres`	The code passes Sevalla’s `postgres://` URL to SQLAlchemy unchanged.	Replace the scheme with `postgresql+psycopg://`, as `database_url()` does.
The job crashes with `invalid interpolation syntax`	The database password contains `%`, and Alembic’s config reads it as a placeholder.	Escape it with `.replace("%", "%%")` in `alembic/env.py`.
The deployment fails at `Migrate has failed`	The migration raised an error, or the application can’t reach the database.	Read the job’s output in the build log. Check that the internal connection exists and that `DB_URL` is set.
The web process crashes with `Path does not exist`	The path in the start command doesn’t match the file with the `FastAPI` app.	Update `[start]` in `nixpacks.toml`, for example `fastapi run app/main.py --port $PORT --forwarded-allow-ips '*'`.
The build fails with `Could not find a version that satisfies the requirement`	The build uses a Python version older than a package supports.	Add `.python-version` with `3.13`.

For more causes, see Troubleshoot builds and deployments. To add file storage, caching or background tasks, see the FastAPI guides.

​Before you begin

​Create the project

​Prepare the project for Sevalla

​Set up migrations

​Pin the Python version

​Set the start command

​List the dependencies

​Deploy to Sevalla

​Verify the deployment

​Deploy changes

​Add a custom domain

​Troubleshoot the deployment