CapaKraken/docs/developer-runbook.md

Developer Runbook

Stand: 2026-04-01
Zweck: Vollständige Referenz für lokales Setup, täglichen Betrieb und Recovery-Szenarien.

---

Erstmaliges Setup (Fresh Checkout)

# 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

docker compose --profile full up -d

Nur Postgres + Redis (ohne App — z. B. für pnpm run dev auf dem Host):

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

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

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:

# 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:

docker compose logs -f app

Warten bis: ✓ Ready on http://0.0.0.0:3100

---

Kompletter DB-Reset

# 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

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