Deploy a FastAPI app

Create the VM#

On your computer (pick another name if my-fastapi is taken):

ssh exe.dev new --name=my-fastapi
ssh my-fastapi.exe.xyz

Everything else runs on the VM, as exedev.

Prepare the VM#

uv is preinstalled. Install Python 3.14 with it, and make the directories for data, backups, and scripts. Then create ~/app.env, the app's settings and secrets, once; systemd and the deploy hook both read it:

uv python install 3.14
mkdir -p ~/data ~/backups ~/bin
if [ ! -e ~/app.env ]; then
  install -m 600 /dev/null ~/app.env
  cat >> ~/app.env <<EOF
# Settings and secrets for app.service and the deploy hook.
# One KEY=value per line, no quotes. Back this file up.
DATABASE_URL=sqlite:///$HOME/data/app.db
WEB_CONCURRENCY=$(nproc)
PORT=8000
EOF
fi
cat ~/app.env

WEB_CONCURRENCY is the number of Uvicorn worker processes: one per vCPU. PORT is for start commands that read it, as on Heroku and Railway; exe.dev sends your app's traffic to port 8000.

Back up nightly#

This script copies each SQLite database in ~/data with sqlite3 .backup, which is safe while the app writes, and checks the copy. It adds the rest of ~/data and ~/app.env, and keeps the 14 newest backups of each kind:

cat > ~/bin/app-backup <<'EOF'
#!/bin/bash
# Back up ~/data and ~/app.env to ~/backups/app-<kind>-<time>.tar.gz.
# SQLite databases (*.db) are copied with .backup, safe while the app runs.
# Keeps the 14 newest backups of each kind. Usage: app-backup [nightly|deploy|manual]
set -euo pipefail
umask 077
kind=${1:-manual}
work=$(mktemp -d)
trap 'rm -rf "$work"' EXIT
mkdir -p "$HOME/backups" "$work/data"
rsync -a --exclude='*.db' --exclude='*.db-wal' --exclude='*.db-shm' "$HOME/data/" "$work/data/"
for db in "$HOME"/data/*.db; do
  [ -e "$db" ] || continue
  copy="$work/data/$(basename "$db")"
  sqlite3 "$db" ".backup '$copy'"
  [ "$(sqlite3 "$copy" 'PRAGMA integrity_check')" = ok ]
done
cp "$HOME/app.env" "$work/"
out="$HOME/backups/app-$kind-$(date -u +%Y%m%d-%H%M%S).tar.gz"
tar -czf "$out.part" -C "$work" .
mv "$out.part" "$out"
ls -1t "$HOME/backups/app-$kind-"*.tar.gz | tail -n +15 | xargs -r rm --
echo "$out"
EOF
chmod +x ~/bin/app-backup

Run it every night at about 03:30 UTC:

sudo tee /etc/systemd/system/app-backup.service >/dev/null <<'EOF'
[Unit]
Description=Back up ~/data and ~/app.env to ~/backups

[Service]
Type=oneshot
User=exedev
ExecStart=/home/exedev/bin/app-backup nightly
EOF
sudo tee /etc/systemd/system/app-backup.timer >/dev/null <<'EOF'
[Unit]
Description=Back up the app every night

[Timer]
OnCalendar=*-*-* 03:30:00
RandomizedDelaySec=30m
Persistent=true

[Install]
WantedBy=timers.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable --now app-backup.timer
systemctl list-timers app-backup.timer

The timer should show its next run.

Run the app with systemd#

fastapi run is FastAPI's production server: Uvicorn, without reloading, with --workers processes. exe.dev's HTTPS proxy reaches the app from 127.0.0.1 and sends X-Forwarded-Proto: https and X-Forwarded-For. Trusting those headers from 127.0.0.1, and only from there, makes FastAPI's redirects and url_for use https://, and gives you the visitor's address in request.client. That's Uvicorn's default; the flags below make it explicit:

sudo tee /etc/systemd/system/app.service >/dev/null <<'EOF'
[Unit]
Description=FastAPI app in ~/app
After=network-online.target
Wants=network-online.target
StartLimitIntervalSec=0

[Service]
User=exedev
WorkingDirectory=/home/exedev/app
EnvironmentFile=/home/exedev/app.env
Environment=PYTHONUNBUFFERED=1
# exe.dev's proxy connects from 127.0.0.1: trust its X-Forwarded-* headers.
ExecStart=/home/exedev/app/.venv/bin/fastapi run --port 8000 --workers ${WEB_CONCURRENCY} --proxy-headers --forwarded-allow-ips 127.0.0.1
Restart=always
RestartSec=3
# Don't wait forever for open streams when restarting.
TimeoutStopSec=20

[Install]
WantedBy=multi-user.target
EOF
sudo systemctl daemon-reload
sudo systemctl enable app.service

It starts with the first deploy. With no path, fastapi run finds the app through [tool.fastapi] entrypoint in pyproject.toml, or in main.py, app.py, api.py, or app/main.py.

Warning

FastAPI's docs suggest --forwarded-allow-ips="*". Don't use it here: exe.dev adds the visitor's address to any X-Forwarded-For the visitor sent, and with * Uvicorn believes the first, made-up entry.

Add the deploy hook#

Create the repository you'll push to. To start fresh:

git init --bare -b main ~/app.git

To bring your app, clone it from GitHub instead, with your repository in place of OWNER/NAME:

git clone --bare https://github.com/OWNER/NAME.git ~/app.git

If that asks for a password, the repository is private. On your computer, connect it with the GitHub integration, then clone through the integration, with no token on the VM:

ssh exe.dev integrations add github --name NAME --repository OWNER/NAME --attach vm:my-fastapi

git clone --bare https://github.int.exe.xyz/OWNER/NAME.git ~/app.git

The branch HEAD points to (main, usually) is the one that deploys; pushes to other branches are stored but not deployed. Now the hook:

cat > ~/app.git/hooks/pre-receive <<'EOF'
#!/bin/bash
# Deploys each push to the deploy branch before git accepts it, or the
# branch as it is when run by hand. Builds it in a new
# ~/releases/<time>-<commit>: installs dependencies with uv, backs up the
# database and runs Alembic migrations. Then points ~/app at the new
# release, restarts app.service, and waits for an answer. Any failure
# rejects the push, and ~/app stays on (or goes back to) the running release.
set -Eeuo pipefail
by_git=${GIT_DIR:+yes}   # git sets GIT_DIR for hooks, so this is a push
export GIT_DIR=$HOME/app.git PATH=$HOME/.local/bin:/usr/local/bin:/usr/bin:/bin
branch=$(git symbolic-ref --short HEAD)
exec 9>"$GIT_DIR/deploy.lock" && flock 9   # one deploy at a time

new=$(git rev-parse -q --verify "refs/heads/$branch" || true)
if [ -n "$by_git" ]; then
  now=${new:-0000000000000000000000000000000000000000} new=
  while read -r was sha ref; do
    if [ "$ref" = "refs/heads/$branch" ]; then new=$sha from=$was; fi
  done
  if [ -z "$new" ]; then echo "deploy: only pushes to $branch deploy"; exit 0; fi
  if [[ $new =~ ^0+$ ]]; then echo "deploy: $branch can't be deleted"; exit 1; fi
  if [ "$from" != "$now" ]; then echo "deploy: $branch moved; pull and push again"; exit 1; fi
fi
old=$(readlink "$HOME/app" || true)   # the live release
release=$HOME/releases/$(date -u +%Y%m%d-%H%M%S)-${new:0:12}
echo "deploy: ${new:0:7} ($branch)"
mkdir -p "$HOME/releases" && mkdir "$release"
trap 'rm -rf "$release"; echo "deploy: FAILED; the live version is unchanged" >&2' ERR
git archive "$new" | tar -x -C "$release"
unset GIT_DIR GIT_QUARANTINE_PATH GIT_OBJECT_DIRECTORY GIT_ALTERNATE_OBJECT_DIRECTORIES
cd "$release"
if [ -f uv.lock ]; then uv sync -q --locked --no-dev
elif [ -f pyproject.toml ]; then uv sync -q --no-dev
else uv venv -q && uv pip install -q -r requirements.txt
fi
set -a; . "$HOME/app.env"; set +a
if [ -f alembic.ini ] || grep -qs '^\[tool\.alembic\]' pyproject.toml; then
  current=$(.venv/bin/alembic current 2>&1 || true)
  if [[ $current == *"Can't locate revision"* ]]; then
    echo "deploy: the database is newer than this commit; not migrating"
  elif [[ $current != *"(head)"* ]]; then
    "$HOME/bin/app-backup" deploy   # a migration is coming: back up first
    .venv/bin/alembic upgrade head
  fi
fi
trap - ERR

go_live() {   # point ~/app at a release, restart, wait 30 s for an answer below 500
  ln -sfn "$1" "$HOME/app.next" && mv -T "$HOME/app.next" "$HOME/app"
  since=$(date +%s)
  sudo systemctl restart app.service
  for _ in $(seq 30); do
    sleep 1
    code=$(curl -s -o /dev/null -w '%{http_code}' http://localhost:8000/) || true
    [ "$code" -ge 200 ] && [ "$code" -lt 500 ] && return 0
  done
  return 1
}
if ! go_live "$release"; then
  echo "deploy: no answer on port 8000. Errors in journalctl -u app:" >&2
  journalctl -u app.service --since "@$since" -o cat |
    grep -E '^[A-Za-z_.]+(Error|Exception)\b' | sort | uniq -c | tail -n 5 >&2 || true
  if [ -z "$old" ]; then echo "deploy: FAILED; fix it and deploy again" >&2; exit 1; fi
  go_live "$old" || true
  rm -rf "$release"
  echo "deploy: FAILED; back to ${old: -12:7}" >&2
  exit 1
fi
if systemctl -q is-enabled app-worker.service 2>/dev/null; then
  sudo systemctl restart app-worker.service
fi
ls -1d "$HOME"/releases/*/ | head -n -3 | xargs -r rm -rf   # keep three
echo "deploy: ${new:0:7} is live at https://$(hostname).exe.xyz/"
EOF
chmod +x ~/app.git/hooks/pre-receive

~/app is a link to the live release: readlink ~/app shows which, and the hook keeps the three newest in ~/releases. Now follow Start fresh or Bring your app.

Start fresh#

The starter is a small notes API: FastAPI, SQLModel tables in SQLite, and Alembic migrations, created with uv the way FastAPI's docs recommend. Make the project in a scratch directory and add the packages:

rm -rf /tmp/starter && mkdir /tmp/starter && cd /tmp/starter
git init -q -b main
uv init --no-package --no-readme --python 3.14 --name "$(hostname)"
uv add "fastapi[standard]" sqlmodel alembic
uv run alembic init migrations
sed -i 's/^import sqlalchemy as sa$/&\nimport sqlmodel/' migrations/script.py.mako
printf '\n[tool.fastapi]\nentrypoint = "main:app"\n' >> pyproject.toml

The sed line lets Alembic's migrations use SQLModel's column types. The tables, and the database connection, go in models.py:

cat > models.py <<'EOF'
"""The database: SQLite in ~/data on the VM (DATABASE_URL), app.db locally."""

import os
from datetime import UTC, datetime

from sqlalchemy import event
from sqlmodel import Field, SQLModel, create_engine

engine = create_engine(os.environ.get("DATABASE_URL", "sqlite:///app.db"))

if engine.dialect.name == "sqlite":

    @event.listens_for(engine, "connect")
    def _sqlite_settings(conn, _):
        # WAL lets requests read while another writes; busy_timeout makes
        # writers in different workers wait their turn instead of failing.
        conn.execute("PRAGMA journal_mode=WAL")
        conn.execute("PRAGMA busy_timeout=5000")


class NoteIn(SQLModel):
    text: str = Field(min_length=1, max_length=2000)


class Note(NoteIn, table=True):
    id: int | None = Field(default=None, primary_key=True)
    author: str | None = None
    created_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
EOF

The API goes in main.py. get_user reads the email exe.dev's proxy adds for signed-in visitors:

cat > main.py <<'EOF'
"""A small FastAPI app: notes in SQLite, signed in with exe.dev."""

from typing import Annotated

from fastapi import Depends, FastAPI, Request
from sqlmodel import Session, select

from models import Note, NoteIn, engine

app = FastAPI(title="Notes")


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


def get_user(request: Request) -> str | None:
    # exe.dev's proxy adds this header for signed-in visitors.
    return request.headers.get("X-ExeDev-Email")


SessionDep = Annotated[Session, Depends(get_session)]
User = Annotated[str | None, Depends(get_user)]


@app.get("/")
def hello(user: User) -> dict:
    return {"hello": user or "stranger", "docs": "/docs"}


@app.get("/notes")
def list_notes(session: SessionDep) -> list[Note]:
    return session.exec(select(Note).order_by(Note.id.desc()).limit(100)).all()


@app.post("/notes", status_code=201)
def add_note(note: NoteIn, session: SessionDep, user: User) -> Note:
    row = Note.model_validate(note, update={"author": user})
    session.add(row)
    session.commit()
    session.refresh(row)
    return row


@app.get("/health")
def health(session: SessionDep) -> dict:
    session.exec(select(1)).one()
    return {"ok": True}
EOF

Alembic's generated env.py expects a URL in alembic.ini; this one uses the app's own engine and tables instead, and SQLite-friendly "batch" migrations:

cat > migrations/env.py <<'EOF'
"""Alembic migrations, run with the app's own engine and models."""

from logging.config import fileConfig

from alembic import context
from sqlmodel import SQLModel

import models

if context.config.config_file_name:
    fileConfig(context.config.config_file_name)

with models.engine.connect() as connection:
    context.configure(
        connection=connection,
        target_metadata=SQLModel.metadata,
        render_as_batch=True,  # SQLite can't ALTER most columns; copy the table instead
    )
    with context.begin_transaction():
        context.run_migrations()
EOF

Generate the first migration against an empty scratch database, and commit:

uv run alembic revision --autogenerate -m "create note table"
rm -f app.db app.db-shm app.db-wal
cat > .gitignore <<'EOF'
__pycache__/
*.py[oc]
.venv/
.env
*.db
*.db-shm
*.db-wal
EOF
git add .gitignore .python-version pyproject.toml uv.lock main.py models.py alembic.ini migrations
git -c user.name="$(hostname)" -c user.email="exedev@$(hostname).exe.xyz" commit -q -m "FastAPI starter"

Push it to ~/app.git. That runs the hook: the first deploy.

git push ~/app.git main && cd ~ && rm -rf /tmp/starter

Expect deploy: ... is live at https://... at the end. Continue with Check it.

Bring your app#

The hook already knows uv projects (uv.lock or pyproject.toml) and requirements.txt, and runs Alembic when alembic.ini is at the top of the repository. Check what else your app expects. Look at its README, Procfile, Dockerfile, or .env.example:

• How it starts. If fastapi run can't find the app by itself, name it in ExecStart in /etc/systemd/system/app.service, for example fastapi run app/main.py or fastapi run --entrypoint backend.main:app. Without fastapi[standard] (or fastapi-cli) in its dependencies, there's no fastapi command: use the app's own start command, from its Procfile, railway.json, or Dockerfile, with .venv/bin/ in front. For Uvicorn, add --workers ${WEB_CONCURRENCY} --proxy-headers --forwarded-allow-ips 127.0.0.1. Other servers, such as Hypercorn, ignore X-Forwarded-* until the app sets that up in code; adding uvicorn to the app's dependencies is the easy way out. Then run sudo systemctl daemon-reload.
• Settings. Add the variables it reads to ~/app.env. Make secrets with openssl rand -hex 32.
• Files. Point SQLite databases and uploads into ~/data, such as DATABASE_URL=sqlite:////home/exedev/data/app.db. Anything written inside ~/app is lost at the next deploy. If the app writes to a fixed relative path, such as sqlite:///./app.db, run it from ~/data: set WorkingDirectory=/home/exedev/data in the service. If the app isn't an installed package, tell the server where the code is: fastapi run /home/exedev/app/main.py, or Uvicorn's --app-dir /home/exedev/app.
• Python. uv uses the version in .python-version or requires-python. A project with only requirements.txt gets the newest installed Python. For another, such as the one in a Heroku runtime.txt, change uv venv in the hook to uv venv --python 3.12.
• Somewhere else. If pyproject.toml isn't at the top of the repository, add that directory to the hook's cd "$release" and to the service's WorkingDirectory and ExecStart. Other release steps go in the hook, before trap - ERR.

Then deploy it once:

~/app.git/hooks/pre-receive

Expect deploy: ... is live at https://.... If it fails, journalctl -u app -n 50 usually says why: a missing setting, or a module that isn't in the dependencies. Fix the setting, or the hook or service, and run it again.

Check it#

systemctl is-active app.service
systemctl is-enabled app.service app-backup.timer
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/docs
curl -s -o /dev/null -w '%{redirect_url}\n' -H "Host: $(hostname).exe.xyz" \
  -H 'X-Forwarded-Proto: https' http://localhost:8000/docs/

Expect active, enabled twice, 200, and https://<vm>.exe.xyz/docs: FastAPI redirected /docs/ to /docs and built the address from the proxy's headers. If it shows http://, check the flags in ExecStart; servers other than Uvicorn need their own setting (see Bring your app). In the starter, curl -s localhost:8000/health says {"ok":true}. sudo reboot, wait a minute, reconnect, and the same checks pass.

Test a backup#

Make a backup and restore it into a scratch directory:

sudo systemctl start app-backup.service
latest=$(ls -1t ~/backups/app-nightly-*.tar.gz | head -n 1)
rm -rf /tmp/restore-test && mkdir /tmp/restore-test
tar -xzf "$latest" -C /tmp/restore-test
ls -la /tmp/restore-test /tmp/restore-test/data
for db in /tmp/restore-test/data/*.db; do
  [ -e "$db" ] && sqlite3 "$db" 'PRAGMA integrity_check' && sqlite3 "$db" .tables
done
rm -rf /tmp/restore-test

Expect app.env, the data directory, and for each database ok and its tables (the starter's are alembic_version and note). Setup is done: continue with Open your API.

On the VM, ~/bin/app-backup makes a backup now and prints its path. Each archive holds data/ (each SQLite database as a consistent copy) and app.env.

Restore#

Pick a backup in ~/backups and use its name below. On a new VM, first follow Set up by hand up to your first deploy, then copy the archive over from your computer:

scp my-fastapi-backups/app-nightly-20261017-033012.tar.gz my-fastapi.exe.xyz:backups/

On the VM, stop the app, set the current data aside, and unpack:

backup=~/backups/app-nightly-20261017-033012.tar.gz
sudo systemctl stop app.service app-worker.service 2>/dev/null || true
mv ~/data ~/data.before-restore-$(date +%s)
rm -rf /tmp/restore && mkdir /tmp/restore && tar -xzf "$backup" -C /tmp/restore
mv /tmp/restore/data ~/data
diff /tmp/restore/app.env ~/app.env

If diff shows settings or secrets you need from the backup (on a new VM, you do), copy them: install -m 600 /tmp/restore/app.env ~/app.env, then set WEB_CONCURRENCY to this VM's nproc. Then bring the schema up to the code's and start again:

cd ~/app && set -a && . ~/app.env && set +a
[ -f alembic.ini ] && .venv/bin/alembic upgrade head
sudo systemctl start app.service
systemctl -q is-enabled app-worker.service 2>/dev/null && sudo systemctl start app-worker.service
sleep 5; curl -s -o /dev/null -w '%{http_code}\n' http://localhost:8000/docs
rm -rf /tmp/restore

Expect 200, and your data in the app. Delete ~/data.before-restore-* once you're happy.

Updates travel through Git like any other change. On your computer:

• Packages: uv lock --upgrade (or --upgrade-package fastapi), run your tests, commit uv.lock, and push. Read FastAPI's release notes first: it's pre-1.0, so minor versions can change behavior.
• Python: change .python-version (to 3.15, say) and requires-python in pyproject.toml, run uv lock, commit, and push. The hook's uv sync downloads that Python for the new release.

On the VM:

• uv: the preinstalled uv is fine for this setup. For a newer one, curl -LsSf https://astral.sh/uv/install.sh | sh installs it in ~/.local/bin, which the hook and your shell try first.
• Ubuntu: sudo apt-get update && sudo apt-get upgrade -y.

On the VM, the app's log, and the live release:

journalctl -u app -n 100 --no-pager
systemctl status app --no-pager
readlink ~/app

• deploy: FAILED and a rejected push: the lines above say why. The lockfile at uv.lock needs to be updated: run uv lock and commit uv.lock. A ModuleNotFoundError after the restart: the package is missing from pyproject.toml. An Alembic error: fix the migration; the database was backed up first, in ~/backups/app-deploy-*.
• Deploy again without a new commit, after fixing a setting, say: on your computer, ssh my-fastapi.exe.xyz app.git/hooks/pre-receive. Settings alone need only sudo systemctl restart app on the VM.
• The push is rejected (non-fast-forward): someone else pushed first, maybe Shelley. git pull exe main, then push.
• Redirects or url_for links use http://: the app doesn't trust the proxy. Check --proxy-headers --forwarded-allow-ips 127.0.0.1 in ExecStart.
• The browser can't reach the app: check that it listens on port 8000 (ss -ltnp | grep 8000). For another port, run ssh exe.dev share port my-fastapi <port> on your computer.
• database is locked: a write took longer than the 5-second busy_timeout. Keep transactions short, or move to PostgreSQL.
• Scripts get 401: check the X-Exedev-Authorization: Bearer header, that the token was made with --vm=my-fastapi, and that it hasn't expired.
• Down after a reboot: sudo systemctl enable --now app.service.