Template
Florian Wilde
75e99f75c6
A published database port puts the data on the public internet, and Docker's own iptables rules bypass ufw — the server looks firewalled while the port is open. Previously this was only a comment in compose.yaml, which an agent adding a db service later is free to ignore. Anchored at every point where a service could be added or shipped: - rules/security.md: the rule, the reasoning, and the audit commands - rules/backend.md + architecture SKILL: constraint when picking the data layer - agents/backend-dev.md: non-negotiable for any service it adds - agents/qa-engineer.md: a published port is a Critical finding - skills/deploy: blocking pre-flight audit - compose.yaml: db example now uses expose:, with depends_on healthcheck - docs/DEPLOYMENT.md + README: SSH tunnel instead of publishing for debugging
179 lines
6.2 KiB
Markdown
179 lines
6.2 KiB
Markdown
# 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.
|
|
|
|
## 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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
|
|
|
|
```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 |
|