refactor: rebuild template — Tailwind v4, Docker self-hosting, passkey auth

Toolchain fixes (all previously broken): - npm run lint: next lint was removed in Next 16 -> eslint with flat config - .eslintrc.json was ignored by ESLint 9 -> eslint.config.mjs - npm test / test:e2e exited 1 with no tests -> passWithNoTests - Vitest scanned tests/ and would have run Playwright specs -> scoped to src/ - Playwright targeted Mobile Safari while docs installed only chromium - reuseExistingServer silently tested a foreign server on :3000 -> E2E_PORT - 11 high-severity vulns -> npm audit fix - deny rule Read(**/.env*) also blocked .env.example -> precise patterns Stack changes: - Tailwind v3 -> v4 (CSS-first, no tailwind.config.ts, tw-animate-css) - shadcn regenerated for v4; 33 components -> 6 core, bundled radix-ui - Supabase removed entirely; data layer is now chosen per project - Vercel removed; Docker Compose self-hosting with scripts/update.sh - Better Auth + passkey plugin as the binding auth standard - ThemeProvider and Sonner mounted; dark mode and toasts now actually work Workflow system: - Sub-agents wired: /frontend, /backend, /qa delegate to .claude/agents - Checklists folded into their SKILL.md; one file per skill - Rules rewritten: DB-agnostic backend, passkey security, v4 frontend - Spec language settled as German, skill instructions English
2026-08-09 00:48:50 +02:00
parent a8b196e92b
commit b0c4e9e9b9
101 changed files with 3651 additions and 7695 deletions
@@ -0,0 +1,148 @@
+# 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 |