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.

```bash
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 |

```bash
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:

```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

```bash
./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.

## Database

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

1. Add it as a second service in `compose.yaml` — no published port, reachable only
   over the internal Compose network
2. Add a named volume for its data
3. Add `DATABASE_URL` to `.env.example`
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

```bash
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

```bash
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:

```bash
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 |