craftvia/docs/DEPLOY-COOLIFY.md

# Deployment: Testserver via Coolify (intern)

> Zielumgebung: interner Coolify-Host (`192.168.1.207`), Docker-Compose-Stack,
> HTTP über eine `*.sslip.io`-Domain (kein öffentliches TLS).
> Ergänzt `docs/HANDOVER-DEVOPS.md`. Deploy-Datei: `docker-compose.coolify.yml`.

## Architekturüberblick (Coolify)

- Coolify deployt den **Compose-Stack** aus diesem Repo und übernimmt **Reverse-Proxy + Routing** — die App wird **nicht** per Host-Port exponiert.
- Services: `migrate` (Init-Job) → `app` (Next.js standalone) + `postgres` (pgvector), `redis`, `garage` (Objektspeicher) + `garage-provision` (Init-Job).
- **Migrationen** laufen als eigener Init-Job `migrate` (`prisma migrate deploy`, schlanke **`migrate`-Stage** ohne `next build`) **vor** `app` — der App-Container migriert selbst nicht.
- **Objektspeicher Garage** (ersetzt MinIO, Community EOL): S3-kompatibel, Single-Node. Buckets/Keys legt NICHT die S3-API an, sondern der Init-Job `garage-provision` (Admin-API, idempotent) **vor** `app`. Details/Cutover: eigener Abschnitt unten.
- **Redis** läuft mit `requirepass` (F-18): `REDIS_PASSWORD` als Coolify-Env setzen und in die `REDIS_URL` einsetzen (`redis://:<pw>@redis:6379`).
- **Netzsegmentierung** (F-18): `postgres`/`redis`/`garage`/`migrate` liegen im internen Netz (`internal: true`, kein Egress); nur `app` ist zusätzlich im default-Netz (Coolify-Proxy). Garage wird nicht per Traefik/Host-Port exponiert.
- **Secrets/Config** kommen aus den **Coolify-Env-Variablen** (Referenz: `.env.coolify.example`), nicht aus einer committeten `.env`.

## 1. Gitea mit Coolify verbinden (Deploy Key)

SSH ist erreichbar (`git@…sslip.io:22`), daher Deploy-Key:

1. **Coolify → Keys & Tokens → Private Keys**: SSH-Key generieren (oder beim Anlegen der Ressource „Private Repository (deploy key)“ automatisch). Öffentlichen Key kopieren.
2. **Gitea → Repo `msolarczek/ISMS-Tool` → Settings → Deploy Keys → Add Deploy Key**: Key einfügen, nur Lesezugriff.
3. Repo-URL in Coolify (SSH):
   `git@gitea-vkbhbn2qdkz5ppk9q4qgb0tn.192.168.1.207.sslip.io:msolarczek/ISMS-Tool.git`

## 2. Ressource anlegen

1. Projekt/Environment wählen → **＋ New → Private Repository (deploy key)**.
2. Repo `ISMS-Tool`, **Branch `devops/coolify-testserver`** (nach erfolgreichem Test → `main`).
3. **Build Pack: Docker Compose**, **Compose Location: `docker-compose.coolify.yml`**.

## 3. Environment-Variablen

Werte aus `.env.coolify.example` in Coolify eintragen. Kritisch:

- Hostnamen = Compose-Service-Namen: `postgres`, `redis`, `garage` (nicht `localhost`); `S3_ENDPOINT=http://garage:3900`.
- `AUTH_SECRET` frisch: `openssl rand -base64 32`.
- `AUTH_URL` = exakt die in Schritt 4 vergebene App-Domain (`http://…`).
- **Garage** (siehe Abschnitt unten): `GARAGE_RPC_SECRET` + `GARAGE_ADMIN_TOKEN` (je `openssl rand -hex 32`), sowie `S3_ACCESS_KEY` = `GK`+24 Hex (`echo "GK$(openssl rand -hex 12)"`) und `S3_SECRET_KEY` = `openssl rand -hex 32`. Alle **literal** setzen (nicht via `${…}` — Coolify-Interpolationsfalle).

## 4. Domain & HTTP

- Beim Service `app` unter **Domains** die `*.sslip.io`-Domain übernehmen, Schema **`http://`**.
- Dieselbe Domain als `AUTH_URL` setzen (sonst schlägt der NextAuth-Login fehl).

## 5. Persistenz

Named Volumes müssen als Persistent Storage erkannt sein — v. a. **`pgdata`** (sonst Datenverlust bei Redeploy) und **`garage_meta`** (Bucket-/Key-/Layout-Definitionen — ohne meta sind die Objektdaten in `garage_data` nicht adressierbar). Ebenso `garage_data`, `redisdata`, `backups`. **`garage_meta` in die Host-Backup-Strategie aufnehmen** (analog `pgdata`).

## 6. Deploy

**Deploy** starten. Reihenfolge: `postgres` (healthy) → `migrate` (läuft einmalig durch) → `app` (startet erst nach erfolgreichem Migrate). Logs von `migrate`/`app` bei Fehlern prüfen.

## 7. Demo-Admin anlegen (einmalig, Testserver)

Der Demo-Seed läuft nicht automatisch. Im Coolify-**Terminal** des `migrate`-Containers (builder-Image, hat `tsx`):

```
npx tsx prisma/seed.ts
```

Login danach: `admin@demo.example` / `Demo1234!`.

> Produktiv: **kein** Demo-Seed. Stattdessen einmaliger Bootstrap des Plattform-Admins
> (`provisionTenant({ admin.isPlatformAdmin: true })`) — Skript noch zu erstellen
> (siehe `docs/HANDOVER-DEVOPS.md` §4).

## 8. Smoke-Test

Über die App-Domain: Login, Admin-Konsole, eine Modul-Seite.

## Redeploy / Migrationen-Nachziehen

Jeder Coolify-Redeploy baut neu und lässt `migrate` erneut laufen (`migrate deploy` ist idempotent — nur neue Migrationen werden angewandt). App startet erst nach erfolgreichem Migrate.

## Von Test zu Produktiv (Delta)

- `AUTH_SECRET`, DB-Passwörter und die **Garage-Secrets** (`GARAGE_RPC_SECRET`, `GARAGE_ADMIN_TOKEN`, `S3_ACCESS_KEY`/`S3_SECRET_KEY`) neu/aus Secret-Store; eigene Domain + gültiges TLS.
- **Kein** Demo-Seed; Erst-Superadmin per Bootstrap-Skript.
- Backups (`pg_dump`/Volume-Snapshots inkl. **`garage_meta`**) + Restore-Test, Monitoring/Alerting.
- Ggf. ≥ 2 `app`-Replicas hinter dem Coolify-Proxy.

## Objektspeicher (Garage) — Cutover, Provisioning & Rollback

Ablösung von MinIO (Community EOL) durch **Garage** (S3-kompatibel, aktiv gepflegt,
Single-Node). Konzept: `docs/KONZEPT-garage-migration.md`. Es gibt **keine produktiven
Daten** → **Neu-Deploy statt Datenmigration** (kein rclone, kein Wartungsfenster).

**Konfig-Bausteine**
- `deploy/garage.toml` (eingecheckt, **secret-frei**): `replication_factor=1`,
  `s3_region=us-east-1`, S3-API `:3900`, Admin-API `:3903`. `rpc_secret`/`admin_token`
  liest der Daemon aus der Env (`GARAGE_RPC_SECRET`/`GARAGE_ADMIN_TOKEN`).
- Volumes: `garage_meta` (**kritisch**, ins Host-Backup) + `garage_data`.
- Init-Job `garage-provision` (`scripts/garage-provision.ts`, Admin-API, **idempotent**):
  Layout → Bucket `isms-documents` → Access-Key **importieren** (aus `S3_ACCESS_KEY/…`)
  → Rechte read/write. Läuft bei jedem Deploy; „already exists“ = Erfolg. Ohne
  `GARAGE_ADMIN_TOKEN` No-op. Loggt **keine** Secrets.

**Cutover-Runbook (Test-Instanz)**
1. Compose enthält bereits `garage` + `garage-provision`; der alte `minio`-Service ist
   auskommentiert (Rollback-Netz) und wird erst nach Abnahme entfernt.
2. Coolify-Env **literal** setzen (nicht `${…}`): `S3_ENDPOINT=http://garage:3900`,
   `S3_REGION=us-east-1`, `S3_BUCKET=isms-documents`, `GARAGE_RPC_SECRET`,
   `GARAGE_ADMIN_TOKEN`, `S3_ACCESS_KEY` (`GK`+24 Hex), `S3_SECRET_KEY` (64 Hex).
3. Deploy. Reihenfolge: `garage` (healthy: `/garage status`) → `garage-provision`
   (legt Layout/Bucket/Key/Rechte an) → `app`. Optionaler DB-Reset nur, falls alte
   Objekt-Referenzen stören (bei frischer/geseedeter Instanz unnötig).
4. Abnahme (§ KONZEPT §9): Upload → Download (`/files/[...key]`) → Backup-Export `.cvb`
   + Download → DSGVO-ZIP → Restore mit Mandanten-Isolation → Backup-Historie List/
   Aufräumen → Negativfall „fehlender Bucket“ = sprechender Fehler.
5. **`garage_meta`** in der Host-Backup-Strategie bestätigen. Erst danach den
   `minio`-Block **und** das Volume `miniodata` aus `docker-compose.coolify.yml` entfernen.

**Rollback** (unkritisch, keine Prod-Daten): `garage`/`garage-provision` wieder aus-,
den auskommentierten `minio`-Block wieder einkommentieren und die alten `S3_*`/
`MINIO_*`-Env setzen; neu deployen. Solange `minio` + `miniodata` noch existieren, ist
das ein reiner Compose-/Env-Wechsel.

**Provisioning erneut anstoßen / debuggen**: Im Coolify-Terminal eines Containers mit
`tsx` (`migrate`-Image) `npx tsx scripts/garage-provision.ts` erneut laufen lassen
(idempotent). „Container weg ohne Logs“ (Coolify entfernt fehlgeschlagene Container
sofort): Provisioning-Ausgabe zusätzlich in eine Datei spiegeln, z. B.
`npx tsx scripts/garage-provision.ts 2>&1 | tee /tmp/garage-provision.log`.