Hartmut
bfdf0a82da
Tests, CSP nonce middleware, SSRF guard, perf-route hardening, Docker env isolation, migration runbook, RBAC E2E coverage. Tickets resolved: - #19: MfaSetup.test.ts — static source tests confirming local QR rendering - #20: ssrf-guard.test.ts (16 tests) + webhook-procedure-support mock fix - #21: /api/perf route.test.ts (5 tests) — header-only auth, fail-closed - #22: middleware.ts (nonce-based CSP) + middleware.test.ts (6 tests); layout.tsx async + nonce prop; CSP removed from next.config.ts - #23: Active-session registry enforcement verified (already in codebase) - #24: docker-compose.yml REDIS_URL hardcoded (no host-env substitution) - #25: docker-compose.yml REDIS_URL + docs/developer-runbook.md created - #26: e2e/dev-system/rbac-data-access.spec.ts (12 tests, 3 roles × 4 procedures) Quality gates: tsc clean, api 1447/1447, web 189/189 passing. Turbo concurrency capped at 2 (package.json) to prevent OOM under parallel test runs. Co-Authored-By: claude-flow <ruv@ruv.net>
201 lines
6.7 KiB
Markdown
201 lines
6.7 KiB
Markdown
# Developer Runbook
|
|
|
|
**Stand:** 2026-04-01
|
|
**Zweck:** Vollständige Referenz für lokales Setup, täglichen Betrieb und Recovery-Szenarien.
|
|
|
|
---
|
|
|
|
## Erstmaliges Setup (Fresh Checkout)
|
|
|
|
```bash
|
|
# 1. Repo klonen
|
|
git clone <url> capakraken && cd capakraken
|
|
|
|
# 2. Root-Env anlegen (NEXTAUTH_SECRET ist Pflicht, kein Default)
|
|
cp .env.example .env
|
|
# .env öffnen und NEXTAUTH_SECRET setzen (min. 32 zufällige Zeichen)
|
|
# Beispiel: openssl rand -hex 32
|
|
|
|
# 3. Docker-Stack starten (Postgres + Redis + App)
|
|
docker compose --profile full up -d
|
|
|
|
# 4. Warten bis gesund, dann Seed ausführen
|
|
docker compose exec app pnpm --filter @capakraken/db exec prisma db seed
|
|
```
|
|
|
|
Der App-Container führt beim Start automatisch `prisma migrate deploy` + `prisma generate` aus (via `tooling/docker/app-dev-start.sh`).
|
|
|
|
---
|
|
|
|
## Täglicher Start
|
|
|
|
```bash
|
|
docker compose --profile full up -d
|
|
```
|
|
|
|
Nur Postgres + Redis (ohne App — z. B. für `pnpm run dev` auf dem Host):
|
|
|
|
```bash
|
|
docker compose up -d postgres redis
|
|
pnpm run dev
|
|
```
|
|
|
|
---
|
|
|
|
## Env-Var-Strategie
|
|
|
|
### Warum Docker-interne URLs hardcodiert sind
|
|
|
|
`docker-compose.yml` setzt `DATABASE_URL` und `REDIS_URL` als **explizite Literal-Strings** — kein `${VAR:-default}`.
|
|
|
|
Hintergrund: Docker Compose löst Shell-Substitutionen (`${VAR:-fallback}`) gegen das **Host-Environment** auf, bevor der Container startet. Hatte der Host ein `DATABASE_URL=postgresql://localhost:5433/...` gesetzt (z. B. für lokale Entwicklung ohne Docker), landete dieser Wert im Container — wo `localhost` der Container selbst ist, nicht der Host. Das brach die DB-Verbindung.
|
|
|
|
Explizite Literal-Werte im `environment:`-Block haben höchste Priorität und können nicht durch Host-Env-Vars überschrieben werden.
|
|
|
|
**Regel:** Docker-interne Service-DNS-Namen (`postgres`, `redis`) dürfen nie in `${...}`-Ausdrücken stehen.
|
|
|
|
### E2E_TEST_MODE — warum doppelt gesetzt
|
|
|
|
Das Flag muss an **zwei Stellen** stehen:
|
|
|
|
| Ort | Wann aktiv |
|
|
|---|---|
|
|
| `docker-compose.yml` → `environment:` | Wenn die App im Docker-Container läuft |
|
|
| `apps/web/.env.local` | Wenn die App lokal per `pnpm run dev` läuft |
|
|
|
|
Next.js lädt `.env.local` via Volume-Mount. Docker Compose liest nur seinen eigenen `environment:`-Block. Beide Quellen sind nötig — es gibt keine gemeinsame "eine Stelle".
|
|
|
|
### Geheime Werte (API-Keys, SMTP, etc.)
|
|
|
|
Secrets werden **nicht** in `docker-compose.yml` gesetzt (versionierte Datei). Sie gehören in:
|
|
|
|
- **Lokale Entwicklung:** root `.env` (gitignored)
|
|
- **Docker-Container:** Env-Block in `docker-compose.yml` ist für nicht-geheime Werte. Geheime Werte kommen via `env_file: .env` in docker-compose (`.env` ist gitignored und wird nie committed).
|
|
|
|
Benötigte Env-Vars für KI-Funktionen:
|
|
|
|
```
|
|
AZURE_OPENAI_API_KEY=<Azure OpenAI API Key>
|
|
GEMINI_API_KEY=<Google Gemini API Key>
|
|
```
|
|
|
|
---
|
|
|
|
## DB-Migration-Strategie
|
|
|
|
### Normale Entwicklung: `migrate dev`
|
|
|
|
```bash
|
|
node scripts/prisma-with-env.mjs migrate dev --name <beschreibender_name>
|
|
```
|
|
|
|
- Erzeugt eine neue Migration unter `packages/db/prisma/migrations/`
|
|
- Wendet sie auf die lokale DB an
|
|
- Aktualisiert den Prisma Client
|
|
- **Immer committen** — die Migration-Datei ist Teil des Repos
|
|
|
|
### Production / Docker: `migrate deploy`
|
|
|
|
```bash
|
|
node scripts/prisma-with-env.mjs migrate deploy
|
|
```
|
|
|
|
- Wendet nur bereits erstellte Migrationen an (kein Schema-Diff)
|
|
- Idempotent: Bereits angewandte Migrationen werden übersprungen
|
|
|
|
### NIEMALS `db push` in einer Migration-verwalteten Umgebung
|
|
|
|
`db push` schreibt Schema-Änderungen direkt in die DB **ohne** einen `_prisma_migrations`-Eintrag. Wird danach `migrate deploy` ausgeführt, scheitert es mit **P3005** ("database schema is not empty").
|
|
|
|
### Recovery P3005 — Bestehende DB ohne Migrations-History
|
|
|
|
Symptom: `prisma migrate deploy` meldet P3005.
|
|
Ursache: DB wurde initial per `db push` aufgesetzt.
|
|
|
|
Lösung:
|
|
|
|
```bash
|
|
# Welche Migrationen existieren?
|
|
ls packages/db/prisma/migrations/
|
|
|
|
# Für jede Migration, die bereits in der DB ist, ausführen:
|
|
node scripts/prisma-with-env.mjs migrate resolve --applied <migration_folder_name>
|
|
# Beispiel:
|
|
# node scripts/prisma-with-env.mjs migrate resolve --applied 20260401000000_active_sessions
|
|
|
|
# Danach: migrate deploy läuft normal durch
|
|
node scripts/prisma-with-env.mjs migrate deploy
|
|
```
|
|
|
|
`migrate resolve --applied` erstellt den `_prisma_migrations`-Eintrag ohne SQL auszuführen — es teilt Prisma mit, dass diese Migration bereits angewandt wurde.
|
|
|
|
---
|
|
|
|
## Container-Neustart nach Code-Änderungen
|
|
|
|
| Änderung | Aktion |
|
|
|---|---|
|
|
| TypeScript-Quellcode | Kein Restart nötig (Hot Reload via Turborepo) |
|
|
| `schema.prisma` geändert | `docker compose restart app` (führt `prisma generate` aus) |
|
|
| Neue Migration erstellt | `docker compose restart app` (führt `migrate deploy` aus) |
|
|
| `docker-compose.yml` geändert | `docker compose --profile full up -d` (recreate) |
|
|
| Node-Module aktualisiert | `docker compose build app && docker compose --profile full up -d` |
|
|
|
|
### Nach `--force-recreate` oder Image-Rebuild
|
|
|
|
Der App-Container benötigt beim ersten Start nach einem Rebuild Zeit für `pnpm install`. Logs prüfen:
|
|
|
|
```bash
|
|
docker compose logs -f app
|
|
```
|
|
|
|
Warten bis: `✓ Ready on http://0.0.0.0:3100`
|
|
|
|
---
|
|
|
|
## Kompletter DB-Reset
|
|
|
|
```bash
|
|
# Stack stoppen
|
|
docker compose --profile full down
|
|
|
|
# Named Volume löschen (verliert alle Daten!)
|
|
docker volume rm capakraken_pgdata
|
|
|
|
# Neu starten — Container führt beim Start Migrationen aus
|
|
docker compose --profile full up -d
|
|
|
|
# Seed ausführen
|
|
docker compose exec app pnpm --filter @capakraken/db exec prisma db seed
|
|
```
|
|
|
|
---
|
|
|
|
## E2E-Tests gegen den Dev-Server
|
|
|
|
```bash
|
|
cd apps/web
|
|
|
|
# Alle Dev-System-Tests
|
|
pnpm exec playwright test --config=playwright.dev.config.ts
|
|
|
|
# Nur RBAC-Tests
|
|
pnpm exec playwright test e2e/dev-system/rbac-permissions.spec.ts --config=playwright.dev.config.ts
|
|
pnpm exec playwright test e2e/dev-system/rbac-data-access.spec.ts --config=playwright.dev.config.ts
|
|
```
|
|
|
|
Voraussetzung: Dev-Server läuft auf `localhost:3100` (Docker oder `pnpm run dev`).
|
|
`E2E_TEST_MODE=true` muss in der laufenden Instanz gesetzt sein (s. o.).
|
|
|
|
---
|
|
|
|
## Häufige Probleme
|
|
|
|
| Problem | Ursache | Fix |
|
|
|---|---|---|
|
|
| P3005 bei `migrate deploy` | DB per `db push` initialisiert | `migrate resolve --applied` für jede bestehende Migration |
|
|
| P1001 "Can't reach database" | `DATABASE_URL` zeigt auf falschen Host | Im Container ist `localhost` der Container selbst; Docker-interne URL (`postgres:5432`) verwenden |
|
|
| tRPC 401 nach E2E-Tests | E2E-Sessions haben echte Sessions aus `active_sessions` verdrängt | `E2E_TEST_MODE=true` setzen (registriert keine `active_sessions`) |
|
|
| Auth-Rate-Limit erschöpft | Zu viele Logins in Tests | `globalSetup` nutzt StorageState; direkte `signIn()`-Calls in Tests minimieren |
|
|
| Timeline leer nach Tests | E2E-Session hat Admin-Session aus `active_sessions` gekickt | Einloggen + E2E_TEST_MODE prüfen |
|