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