code-vorlage/docs/DEPLOYMENT.md

Deployment

Self-hosted Docker Compose. One app container, published on loopback; a reverse proxy already running on the host terminates TLS and forwards to it.

Files

File	Purpose
Dockerfile	Three-stage build → Next.js standalone bundle, runs as an unprivileged user
compose.yaml	The app service, healthcheck, log rotation
.dockerignore	Keeps the build context small — no node_modules, no .env, no docs
scripts/update.sh	Pull, rebuild, restart, roll back if unhealthy
.env.example	Every variable the app needs, with dummy values

First deployment

Prerequisites on the server: Docker with the Compose plugin, a reverse proxy, and a DNS record pointing at it.

git clone <repo-url> /srv/<app-name>
cd /srv/<app-name>
cp .env.example .env

Edit .env:

Variable	Notes
NEXT_PUBLIC_APP_URL	The real public URL. With auth this must match the domain exactly — the WebAuthn relying-party ID is derived from it, and a mismatch breaks every passkey without a clear error.
APP_PORT	Host port the reverse proxy forwards to
APP_BIND	Leave at 127.0.0.1 unless the container must be publicly reachable
BETTER_AUTH_SECRET	openssl rand -base64 32, unique per environment

docker compose up -d --build
curl -fsS http://127.0.0.1:3000/api/health   # {"status":"ok"}

Reverse proxy

Forward to 127.0.0.1:$APP_PORT and pass through X-Forwarded-Proto and X-Forwarded-Host — without them redirects and WebAuthn origin checks fail.

nginx:

location / {
    proxy_pass         http://127.0.0.1:3000;
    proxy_http_version 1.1;
    proxy_set_header   Upgrade           $http_upgrade;
    proxy_set_header   Connection        "upgrade";
    proxy_set_header   Host              $host;
    proxy_set_header   X-Forwarded-Proto $scheme;
    proxy_set_header   X-Forwarded-Host  $host;
    proxy_set_header   X-Forwarded-For   $proxy_add_x_forwarded_for;
}

Caddy:

app.example.com {
    reverse_proxy 127.0.0.1:3000
}

Passkeys require HTTPS in production. Localhost is the only exemption.

Updates

./scripts/update.sh              # deploy the current branch's latest commit
./scripts/update.sh --force      # rebuild even without a new commit
./scripts/update.sh --branch dev # deploy another branch

What it does: refuses to run on a dirty working tree, fast-forwards to origin/<branch>, rebuilds, restarts, then polls the container healthcheck for up to HEALTH_TIMEOUT seconds (default 120). If the container never turns healthy it prints the last 50 log lines, resets to the previous commit, rebuilds and restarts that — so a bad deploy self-heals instead of leaving the site down.

Port exposure

Only the app service publishes a port, and only on loopback. Everything else — database, cache, queue, admin UI — gets no ports: entry. Services reach each other by name over the Compose network, which needs nothing published:

DATABASE_URL=postgres://user:pass@db:5432/app

ports: "5432:5432" binds 0.0.0.0, which means the database is on the public internet. And Docker writes its own nat/DOCKER-USER iptables rules, so ufw does not block it — the server looks firewalled while the port is open. This is a routine way self-hosted stacks get breached.

Need access for debugging? Do not publish the port. Use an SSH tunnel:

ssh -L 5432:localhost:5432 user@server \
    -t 'docker compose -f /srv/app/compose.yaml exec db psql -U postgres'

Audit what is really bound before and after every deploy:

docker compose config | grep -B8 "published:"          # declared
docker compose ps --format "{{.Service}}\t{{.Ports}}"  # actual
ss -tlnp | grep -v 127.0.0.1                           # what the host exposes

Database

The template ships none by design. When /architecture picks one:

1. Add it as a second service in compose.yaml — no ports: entry, reachable only over the internal Compose network. Use expose: if you want it documented.
2. Add a named volume for its data
3. Add DATABASE_URL to .env.example (pointing at the service name, e.g. db:5432)
4. Run migrations before the new container serves traffic. Either add a short-lived migrate service that the app depends on, or add the migration command to scripts/update.sh between build and restart.
5. Set up a backup for the volume — a volume is not a backup

Operations

docker compose logs -f app       # follow logs
docker compose ps                # status incl. health
docker compose restart app       # restart without rebuilding
docker compose down              # stop the stack
docker compose exec app sh       # shell inside the container

Logs rotate at 10 MB with 3 files kept, configured in compose.yaml.

Manual rollback

git reset --hard <previous-sha>
docker compose up -d --build

Security headers

Set in next.config.ts: X-Frame-Options: DENY, X-Content-Type-Options: nosniff, Referrer-Policy: origin-when-cross-origin, Strict-Transport-Security.

Verify after deploying that the proxy did not strip them: DevTools → Network → pick a request → Response Headers.

A Content-Security-Policy is deliberately not preconfigured — it breaks apps when guessed. Add it per project, starting with Content-Security-Policy-Report-Only.

Error tracking

Not preinstalled. When you want it, Sentry is the usual choice:

npx @sentry/wizard@latest -i nextjs

It edits next.config.ts — re-check that the headers() block survived, and add SENTRY_DSN to .env.example.

Troubleshooting

Symptom	Cause
Builds locally, fails in Docker	Build-time dependency sits in devDependencies
Env var undefined at runtime	Missing in the server's .env, or needs the NEXT_PUBLIC_ prefix for client use
Container healthy, proxy returns 502	Proxy points at the wrong port, or APP_BIND is not reachable from it
Redirect loop	Proxy not forwarding X-Forwarded-Proto
Passkeys fail after deploy	NEXT_PUBLIC_APP_URL mismatch, or no HTTPS
update.sh refuses to start	Uncommitted changes on the server — commit or discard them