Deploying to a VPS

Any Ubuntu 24.04 box works, whether Hetzner, DigitalOcean or Vultr. Four vCPU and 8 GB is comfortable for an app and its database.

Point DNS at the server

An A record for the hostname you will put in DOMAIN, TTL 300 until you are happy.

Do this first. Caddy cannot issue a certificate before DNS resolves to the machine.

Create a deploy user and install Docker

As root on the fresh box:

adduser deploy && usermod -aG sudo deploy
# copy your SSH key to /home/deploy/.ssh/authorized_keys, then disable
# root login and password auth in /etc/ssh/sshd_config

apt update && apt install -y ca-certificates curl git ufw fail2ban unattended-upgrades
curl -fsSL https://get.docker.com | sh
usermod -aG docker deploy

ufw allow OpenSSH && ufw allow 80/tcp && ufw allow 443/tcp && ufw allow 443/udp
ufw enable

Get the code onto the server

As deploy:

sudo mkdir -p /opt/myapp && sudo chown deploy:deploy /opt/myapp
git clone git@github.com:you/myapp.git /opt/myapp

Write .env on the server

This file never enters git and never goes into the image. It is the single source of truth for production secrets.

cd /opt/myapp
cp .env.example .env
chmod 600 .env
nano .env

At minimum:

.env

DOMAIN=example.com
POSTGRES_PASSWORD=          # python -c "import secrets; print(secrets.token_urlsafe(32))"
SECRET_KEY=                 # python -c "import secrets; print(secrets.token_urlsafe(48))"
GOOGLE_CLIENT_ID=
GOOGLE_CLIENT_SECRET=

docker-compose.yml reads DOMAIN and POSTGRES_PASSWORD itself for interpolation, and passes the whole file into the containers with env_file: .env. So POSTGRES_PASSWORD is written once and DATABASE_URL is built from it.Leave FLASK_CONFIG, PORT, WEB_CONCURRENCY, DATABASE_URL, REDIS_URL and JOB_BACKEND out of this file. Compose sets them on the container, and a duplicate here only creates a way for the two to disagree.

Run feather env check to see which keys your config.py reads and which are still missing. It exits non-zero when a key with no fallback is unset, so it works as a CI or deploy gate.

Deploy

./deploy/deploy.sh

Watch the first run. Caddy requests a certificate while the app starts, and docker compose logs -f caddy shows whether issuance worked. When the script prints Healthy. Deploy complete. the site is live over HTTPS.

What deploy.sh does

./deploy/deploy.sh          # deploy the current checkout
./deploy/deploy.sh --pull   # git pull --ff-only first

In order:

docker compose build builds every service. Web and worker are separate images despite sharing a Dockerfile, and building only web leaves the worker on last week’s code.
docker compose up -d db redis starts dependencies, so the migration step has something to talk to.
docker compose run --rm web feather db upgrade runs migrations once, in a throwaway container built from the new image. The old containers keep serving while this happens, so a failed migration leaves the site up.
docker compose up -d --remove-orphans swaps the containers.
Wait for health. It polls Docker’s health status for the web container, which runs curl /health, which checks the database, for up to 120 seconds. On success it prunes dangling images and exits 0. On failure or timeout it dumps the last 50 log lines and exits 1.

The ordering is what matters. Migrations run exactly once, against the image about to serve traffic, before any long-lived container starts. Two web containers can never race on the same Alembic upgrade, and a failed migration is never a partial deploy.

Rolling back

There is no automatic rollback. If a deploy goes wrong, check out the previous commit and run ./deploy/deploy.sh again. Migrations already applied are not reverted, so undo those deliberately with feather db downgrade. To confirm where the database actually is:

docker compose exec -T db psql -U myapp -d myapp -c "SELECT version_num FROM alembic_version;"

TLS and the proxy headers

Caddy obtains and renews Let’s Encrypt certificates for every hostname in deploy/Caddyfile. There is nothing to run, no certbot cron, and no renewal to forget.

deploy/Caddyfile

{$DOMAIN} {
	encode gzip zstd

	reverse_proxy web:8000 {
		header_up X-Real-IP {remote_host}
	}
}

{$DOMAIN} comes from .env via compose. To serve www as well, add a second block. A certificate is issued for each hostname in the file.

www.example.com {
	redir https://example.com{uri} permanent
}

Two load-bearing headers

X-Forwarded-Proto and Host

Caddy sets these by default and Feather’s ProxyFix reads them. Without them Google OAuth builds an http:// redirect URI, and secure session cookies are dropped on every response.

X-Real-IP

Caddy does not set this one, which is why the generated config does. Rate limiting and any geo logic read it, and they fail silently when it is missing.

After editing the Caddyfile, validate before reloading:

docker compose exec -T caddy caddy validate --config /etc/caddy/Caddyfile
docker compose exec -T caddy caddy reload --config /etc/caddy/Caddyfile

Get started

Tutorial: build a Kanban app

Building the UI

Backend

Features

Tooling

Testing

Deployment

Deploying to a VPS

What deploy.sh does

Rolling back

TLS and the proxy headers

Two load-bearing headers

​What deploy.sh does

​Rolling back

​TLS and the proxy headers

​Two load-bearing headers

What deploy.sh does

Rolling back

TLS and the proxy headers

Two load-bearing headers