certvia/docs/HANDOVER-DEVOPS.md

# DevOps-Übergabe — ISMS-Tool (Deployment Test → Produktiv)

> Stand: 2026-07-20 · Branch `main` · Commit `081c000`
> Zweck: Betrieb/Deployment. Gemeinsame Arbeit an Dockerfile, Einrichtung Testserver (remote), danach Produktivserver.
> Ergänzt: `docs/HANDOVER-DEV.md` (App-Architektur/Setup) und `docs/HANDOVER-PM.md` (fachlicher Status).

---

## 1. Überblick der Runtime

Die App ist eine **Next.js-16-Anwendung im Standalone-Modus** (`output: "standalone"` in `next.config`, Start via `node server.js`), zustandslos horizontal skalierbar. Zustand liegt ausschließlich in den Backing-Services.

| Service | Image / Herkunft | Port | Zweck | Persistenz |
|--------|------------------|------|-------|-----------|
| **app** | Multi-Stage-Build (`Dockerfile`) | 3000 | Web-App (Next.js standalone) | zustandslos |
| **postgres** | `pgvector/pgvector:pg16` | 5432 | Primärdatenbank (inkl. `vector`-Extension) | Volume `pgdata` |
| **redis** | `redis:7-alpine` | 6379 | Cache/Queue (für späteren BullMQ-Worker) | Volume `redisdata` |
| **minio** | `minio/minio:latest` | 9000/9001 | Objektspeicher (noch **ungenutzt**; für kommenden Logo-/Datei-Upload) | Volume `miniodata` |
| **mailhog** | `mailhog/mailhog` (Profil `dev`) | 1025/8025 | SMTP-Fang für Entwicklung | — |
| **worker** | s. Dockerfile (Profil `worker`) | — | **noch nicht lauffähig** (kein `worker`-npm-Script vorhanden) | — |

Alles bereits als **`docker-compose.yml`** im Repo-Root beschrieben; **`Dockerfile`** ist ein sauberer 3-Stage-Build (`deps` → `builder` mit `prisma generate` + `next build` → schlanker `runner` als non-root `app`-User).

---

## 2. Umgebungsvariablen (`.env`)

Vorlage: **`.env.example`**. Vollständige Liste:

| Variable | Zweck | Prod-Hinweis |
|----------|-------|-------------|
| `POSTGRES_USER` / `POSTGRES_PASSWORD` / `POSTGRES_DB` | Compose-Init von Postgres | **Secret** (Passwort) |
| `DATABASE_URL` | Prisma-Verbindungsstring | **Secret**; muss auf denselben DB-Nutzer/-Namen zeigen |
| `REDIS_URL` | Redis-Verbindung | — |
| `AUTH_SECRET` | NextAuth-Signaturschlüssel (JWT) | **Secret**, zwingend gesetzt & stark |
| `AUTH_URL` | Öffentliche Basis-URL der App | pro Umgebung (Test/Prod) unterschiedlich, inkl. `https://` |
| `AI_PROVIDER` / `AI_API_KEY` | KI-Chat / KI-Formulierungshilfe (noch ungenutzt) | Secret, optional |
| `SMTP_HOST/PORT/USER/PASSWORD/FROM` | E-Mail (noch ungenutzt; Einladungs-/Benachrichtigungsflow offen) | Secret, optional |
| `MINIO_ROOT_USER` / `MINIO_ROOT_PASSWORD` | Objektspeicher | **fehlen in `.env.example`** → für Prod ergänzen (sonst Compose-Defaults `isms`/`isms-secret`) |

> **Secrets** gehören nicht ins Git. Für Prod: Secret-Management (Docker Secrets / Env aus Vault / CI-Variablen). `.env.example` enthält nur Namen/Defaults.

---

## 3. Build & Start

```bash
# Image bauen
docker compose build app

# Test/lokal hochfahren (ohne dev-only mailhog)
docker compose up -d postgres redis minio app

# mit Mailhog (Dev):   docker compose --profile dev up -d
# Worker (aktuell NICHT lauffähig, s. §6): docker compose --profile worker up -d worker
```

App danach unter `AUTH_URL` (Port 3000) erreichbar.

---

## 4. ⚠️ Datenbank-Migrationen & Bootstrap (kritisch)

**Der App-Container führt KEINE Migrationen beim Start aus** (CMD ist `node server.js`). Migrationen und das erste Provisioning sind ein **separater Deploy-Schritt**:

1. **Migrationen anwenden:** `npx prisma migrate deploy` gegen die Ziel-DB.
   - Die `runner`-Stage enthält Prisma-CLI/`tsx` **nicht** (nur Runtime-Trace). Migrationen daher aus der **`builder`-Stage** (voller `node_modules`) oder aus einem eigenen **Migrations-Job/CI-Step** fahren. → **Designentscheidung mit DevOps** (z. B. Init-Container `command: npx prisma migrate deploy` mit builder-Image, `restart: "no"`).
   - Die Init-Migration legt `CREATE EXTENSION IF NOT EXISTS "vector"` an (pgvector) — das Postgres-Image bringt die Extension mit.
2. **Erster Mandant / Superadmin (Prod):** Der Demo-Seed (`prisma/seed.ts`) ist **nur für Entwicklung** (Demo-Mandant + Testnutzer) — **nicht in Produktion ausführen**. In Prod erfolgt das Anlegen von Kunden über die **Admin-Konsole** (`provisionTenant`). **Offen:** Es gibt aktuell **kein Bootstrap-Skript** für den allerersten Plattform-Admin — dieser muss initial angelegt werden (Skript/One-Off gegen `provisionTenant` mit `isPlatformAdmin: true`, oder manuell). → **Mit App-Entwickler abstimmen** (kleiner Task).

---

## 5. Persistenz, Backup & Restore

- **Volumes:** `pgdata` (kritisch), `miniodata` (künftig Uploads), `redisdata` (unkritisch, Cache).
- **Backups Prod:** regelmäßiger `pg_dump` (logisch) oder Volume-/Snapshot-Backup; MinIO-Bucket-Backup, sobald Uploads aktiv. Aufbewahrung + Restore-Test einplanen (DSGVO-Löschkonzept ist app-seitig noch offen).
- Mandantentrennung ist **logisch** (eine DB, `tenant_id` + Postgres-RLS + App-Guard) — Backups umfassen alle Mandanten gemeinsam.

---

## 6. Bekannte Lücken / To-dos für DevOps

1. **`worker`-Service nicht lauffähig:** Es existiert **kein `npm run worker`**-Script (BullMQ-Scheduler ist app-seitig noch nicht implementiert). Profil `worker` bis dahin **nicht** starten.
2. **Migrations-/Bootstrap-Strategie** festlegen (§4) — Migrations-Job + Erst-Superadmin.
3. **MinIO-Env** in `.env` für Prod ergänzen; MinIO wird erst mit dem kommenden Logo-/Datei-Upload wirklich genutzt (Bucket-Präfix je Mandant vorgesehen).
4. **Reverse-Proxy + TLS** vor der App (Port 3000 nicht direkt exponieren): Traefik/Caddy/nginx mit HTTPS; `AUTH_URL` auf die öffentliche `https://`-Adresse setzen. Rate-Limiting/IP-Härtung für Login/Admin einplanen.
5. **Ressourcen/Skalierung:** `app` ist zustandslos → mehrere Replicas möglich; Sticky-Sessions nicht nötig (JWT). Postgres/Redis als Singleton bzw. Managed-Service.
6. **Health/Observability:** Postgres-Healthcheck vorhanden; für `app` einen HTTP-Healthcheck/Readiness ergänzen (derzeit keiner definiert). Log-Aggregation + Alerting einrichten.
7. **`AUTH_SECRET`** je Umgebung eindeutig & stark; bei Rotation invalidieren alle Sessions.

---

## 7. Test- vs. Produktivumgebung — Unterschiede

| Aspekt | Test (Remote) | Produktiv |
|--------|---------------|-----------|
| Daten | ggf. Demo-Seed erlaubt | **kein Demo-Seed**; nur echtes Provisioning |
| Secrets | Test-Werte | echte Secrets aus Secret-Store |
| Mail | Mailhog (Profil `dev`) | echtes SMTP-Relay |
| TLS | optional/self-signed | verpflichtend, gültiges Zertifikat |
| Backups | optional | verpflichtend + Restore-Test |
| Skalierung | 1 Replica | ≥ 2 App-Replicas hinter Proxy |

---

## 8. Deploy-Checkliste (Kurz)

**Testserver:**
1. Repo klonen/pullen (Gitea, Branch `main`).
2. `.env` aus `.env.example` mit Test-Werten (inkl. `MINIO_*`).
3. `docker compose build app`.
4. `docker compose up -d postgres redis minio`.
5. **Migrationen:** `prisma migrate deploy` (builder-Image/Job).
6. **Erst-Superadmin** anlegen (One-Off, s. §4) — für Test ggf. Demo-Seed ok.
7. `docker compose up -d app`; Reverse-Proxy/TLS davor; Smoke-Test (Login, Admin-Konsole, Modul-Seite).

**Produktivserver:** wie oben, aber Secret-Store, **kein** Demo-Seed, TLS verpflichtend, Backups + Monitoring aktiv, ≥ 2 App-Replicas, Migrations-/Bootstrap-Schritt in die Deploy-Pipeline integriert.

---

## 9. Referenzen im Repo
`Dockerfile`, `docker-compose.yml`, `.env.example`, `next.config.*` (`output: standalone`), `prisma/schema.prisma` + `prisma/migrations/**` (inkl. RLS-Policies & pgvector), `prisma/seed.ts` (nur Dev), `src/server/provision.ts` (Provisioning-Logik für Prod-Onboarding).