Hartmut
4a5edeef3e
CI / Unit Tests (pull_request) Successful in 5m46s
CI / Lint (pull_request) Failing after 3m49s
CI / E2E Tests (pull_request) Has been skipped
CI / Fresh-Linux Docker Deploy (pull_request) Has been skipped
CI / Assistant Split Regression (pull_request) Failing after 35s
CI / Architecture Guardrails (pull_request) Failing after 2m14s
CI / Typecheck (pull_request) Successful in 4m22s
CI / Build (pull_request) Has been skipped
CI / Release Images (pull_request) Has been skipped
- @capakraken/* → @nexus/* across 12 packages (root + 11 workspaces),
1551 import lines migrated via codemod
- User-visible brand strings renamed (emails, page titles, PWA
manifest, mobile header, MFA backup-codes header, tooltips, signin
page, invite page, weekly digest, install prompt)
- TOTP issuer "CapaKraken" → "Nexus" (existing secrets still valid;
re-enrollment relabels them in users' authenticator apps)
- Function rename: assertCapaKrakenDbTarget → assertNexusDbTarget
- LocalStorage migration shim in apps/web/src/app/layout.tsx copies
capakraken_* → nexus_* on first load (guarded by nexus_migrated_v1
sentinel; runs once per browser, then never again)
- Service-worker cache name capakraken-v2 → nexus-v2 with one-time
caches.delete('capakraken-v2') from the same shim
- Email-domain fixtures @capakraken.{dev,app} → @nexus.{dev,app} in
seed data, e2e specs, SMTP default fallback
- Dockerfile.dev / Dockerfile.prod / all .github/workflows/*.yml
pnpm --filter @capakraken/* → @nexus/*
- README, CLAUDE.md, LEARNINGS.md, all docs/*.md, .env.example,
tooling/deploy/.env.production.example brand sweep
Phase 1 deliberately leaves untouched (handled in Phase 3 cutover):
- PostgreSQL DB name "capakraken" and POSTGRES_USER "capakraken"
- Volume names capakraken_pgdata etc.
- Compose project name "capakraken" / "capakraken-prod"
- db-target-guard default expectedDatabase
- env-var CAPAKRAKEN_EXPECTED_DB_NAME
- Container DNS names in docker-compose.ci.yml
Quality gates green: pnpm typecheck (7/7), pnpm test:unit (7/7),
pnpm lint (0 errors), check:exports/imports/architecture all pass.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
201 lines
7.7 KiB
Markdown
201 lines
7.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> nexus && cd nexus
|
|
|
|
# 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 @nexus/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 nexus_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 @nexus/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 |
|