Claude Fable 5
a758c9d78b
All checks were successful
CI / Lint, typecheck, test (pull_request) Successful in 6m45s
CI / Build container images (pull_request) Successful in 1m14s
CI / Auth e2e pack (pull_request) Successful in 8m37s
CI / Import/export fidelity gate (pull_request) Successful in 57s
CD / Build and push images (push) Successful in 21s
CD / Deploy to Test (push) Successful in 12s
CD / Smoke tests against Test (push) Successful in 1m16s
CD / Promote to Int (push) Successful in 28s
CI / Lint, typecheck, test (push) Successful in 6m19s
CI / Build container images (push) Has been skipped
CI / Auth e2e pack (push) Successful in 8m12s
CI / Import/export fidelity gate (push) Successful in 58s
The ADR 0024 §4 decision, taken explicitly and both ways: customers OPERATE prebuilt digest-pinned images (no customer-side build), and ADDITIONALLY the workspace build is verified to work with networking disabled - so site-local patching stays possible without internet. Evidence (docs/vs-nfd/96-offline-build-protokoll.md): pnpm install --offline --frozen-lockfile plus pnpm build under docker run --network none (node:22.15.1-alpine + pnpm 11.9.0, the pinned toolchain), reproduced twice from clean checkouts with identical results. The offline kit is the pnpm store (~870 MB) plus the build user's ~/.cache (~460 MB - the prisma engines live there; without the cache the prisma postinstall fails offline). The one network dependency found and bounded: the drawio plugin's installable ZIP fetches its pinned vendor tarball on first build. Deploy images contain no plugin ZIPs, so the delivery-relevant build is fully offline (CI=1 skips the fetch, as in CI); an offline ZIP build pre-seeds the tarball into packages/plugins/drawio/vendor/. Also catches up the operations manual's scheduler-job table to 10 (read-trail-maintenance was added in #224 without the row here). Refs #219. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01AUtYMxwTCMHG9mVHnwbFg8
228 lines
17 KiB
Markdown
228 lines
17 KiB
Markdown
# Betriebshandbuch (VS-NfD, Issue #229)
|
||
|
||
Zweck: der Betreiber führt die Instanz ohne uns — auch an dem Tag, an
|
||
dem etwas ausfällt. Dieses Handbuch bündelt die betrieblichen
|
||
Prozeduren und verweist für Schrittfolgen auf die maßgeblichen
|
||
Runbooks im Repository, statt sie zu duplizieren. Das Kapitel mit dem
|
||
größten VS-Gewicht ist **§5 Löschung und Vernichtung**; es baut auf der
|
||
vollständigen Kopienliste der Sicherheitsdokumentation auf
|
||
(`60-sicherheitsdokumentation.md` §5).
|
||
|
||
**Belegstufen.** Jede Prozedur nennt am Ende ihren Erprobungsstand:
|
||
|
||
- ✅ _erprobt_ — vom Autor bzw. automatisiert mindestens einmal real
|
||
ausgeführt, mit Beleg.
|
||
- ⚠️ _Mechanik vorhanden, nicht geprobt_ — implementiert und getestet,
|
||
aber noch nie im Ernstfall/als Übung durchgespielt.
|
||
- ⏳ _offen_ — kommt mit dem genannten Issue.
|
||
|
||
---
|
||
|
||
## 1 Installation
|
||
|
||
Referenz: `deploy/stages.md` (maßgebliche Schrittfolge),
|
||
`docs/self-hosting/README.md`.
|
||
|
||
1. Host-Voraussetzungen: Docker + Compose, ein Reverse Proxy mit TLS
|
||
(oder das mitgelieferte `caddy`-Compose-Profil).
|
||
2. `deploy/compose/docker-compose.yml` + `.env` (Vorlage
|
||
`.env.example`; **niemals** eine echte `.env` ins Repo — CI-Zaun
|
||
#198) auf den Host bringen; `COMPOSE_PROJECT_NAME`, Ports
|
||
(`WEB_PORT`/`API_PORT`/`COLLAB_PORT`), `POSTGRES_PASSWORD`, Secrets
|
||
setzen.
|
||
3. `docker compose pull && docker compose up -d` — die api wendet
|
||
Migrationen beim Start selbst an (`MIGRATE_ON_START`); es gibt
|
||
keinen separaten Migrationsschritt.
|
||
4. Erststart: der Setup-Wizard (Issue #80) legt das Admin-Konto an und
|
||
verriegelt sich danach dauerhaft; bis zum Abschluss ist nur
|
||
`/setup/*` erreichbar.
|
||
5. Reverse Proxy: `/` → web, `/api` → api, `/collab` → collab mit
|
||
WebSocket-Upgrade (Portliste: Sicherheitsdokumentation §2).
|
||
6. Für VS-NfD-Betrieb anschließend die Referenzkonfiguration aus dem
|
||
Härtungsleitfaden (`50-haertungsleitfaden.md`) anwenden und mit
|
||
dessen Checkliste verifizieren.
|
||
|
||
Belegstufe: ✅ erprobt — die Stages Test/Int/Prod auf ONE sind exakt
|
||
nach dieser Prozedur aufgesetzt und laufen produktiv (`deploy/stages.md`
|
||
dokumentiert die realen Instanzen).
|
||
|
||
**Airgap-/Offline-Variante:** teilweise verfügbar —
|
||
|
||
- **Mirror-Verfahren (#218): ✅ verfügbar und einmal end-to-end
|
||
ausgeführt.** Schrittfolge: Image-Liste generieren
|
||
(`deploy/scripts/list-images.sh` — nie von Hand pflegen),
|
||
digest-erhaltend kopieren (`docker buildx imagetools create`), Digest
|
||
im Spiegel gegen den Compose-Pin verifizieren, Deployment per
|
||
`REGISTRY_PREFIX` (Dritt-Images) bzw. `IMAGE_PREFIX` (eigene Images)
|
||
auf den Spiegel zeigen. Vollständige Prozedur:
|
||
`deploy/stages.md` §5b; Ausführungsnachweis:
|
||
`95-mirror-protokoll.md`.
|
||
- **Netzloser Build (#219): ✅ verifiziert und entschieden.** Betrieb
|
||
läuft aus Prebuilt-Images; zusätzlich ist der Workspace-Build ohne
|
||
Netz zweifach reproduziert (Offline-Kit = pnpm-Store + Build-Cache;
|
||
einzige Grenze: das installierbare drawio-Plugin-ZIP braucht sein
|
||
vorab abgelegtes Vendor-Tarball). Entscheidung und Prozedur:
|
||
ADR 0024 §Decisions, Nachweis: `96-offline-build-protokoll.md`.
|
||
- ⏳ offen: Testlauf in isolierter Umgebung (#220), Offline-Update-Pfad
|
||
(#221); Meilenstein M28. Bereits vorhanden als Grundlage: alle
|
||
Dritt-Images digest-gepinnt (#203), ein authoritativer Node-Pin
|
||
(#236), SBOMs je Release (#202).
|
||
|
||
## 2 Update und Rollback
|
||
|
||
Referenz: `docs/architecture/operations.md` §Update strategy,
|
||
`deploy/stages.md`.
|
||
|
||
- **Stages:** Merge auf `main` → CD baut Images, deployt Test, führt
|
||
Smoke-Tests aus, promotet Int. CD synct **keine** Compose-Dateien —
|
||
Compose-Änderungen werden von Hand auf den Host übernommen, sonst
|
||
räumt `--remove-orphans` manuell ergänzte Container ab.
|
||
Belegstufe: ✅ erprobt (läuft bei jedem Merge; zuletzt CD-Lauf 568).
|
||
- **Produktion:** ausschließlich getaggte Releases. `git tag vX.Y.Z`
|
||
baut die Versions-Images und führt die Update-Simulation als Gate
|
||
aus; `git tag prod-vX.Y.Z-initial` pinnt die Version in der
|
||
Prod-`.env` und rollt aus (readyz-Poll). Migrationen laufen beim
|
||
api-Start; **Rückwärtsmigrationen gibt es nicht** — Rollback setzt
|
||
deshalb ein DB-kompatibles Vorgängerimage voraus (Migrations-Kaveat;
|
||
im Zweifel Restore aus dem Backup-Set der Vorversion).
|
||
Belegstufe: ✅ erprobt (alle Prod-Versionen bis v0.12.0 so
|
||
ausgerollt).
|
||
- **Rollback:** `git tag prod-v<prev>-rollback1` pinnt die Vorversion
|
||
zurück. Belegstufe: ⚠️ Mechanik vorhanden, nicht geprobt — ein realer
|
||
Rollback war bisher nie nötig; die Übung steht aus.
|
||
- **Dritt-Image-Digest heben:** Prozedur `deploy/stages.md` §5a
|
||
(imagetools inspect → Compose-Referenz ändern → CI bestätigt → Stage-
|
||
Composes von Hand nachziehen → `docker inspect` verifiziert).
|
||
Belegstufe: ✅ erprobt (Rollout #203 am 31.07.2026).
|
||
- **Offline-Update:** ⏳ offen (#221, M28).
|
||
|
||
## 3 Backup und Restore
|
||
|
||
Referenz: `docs/operations/restore-runbook.md` (maßgeblich),
|
||
`deploy/backup-basel.md`, ADR 0015/0026.
|
||
|
||
- Nächtlich erzeugt der backup-Sidecar ein konsistentes Restore-Set
|
||
(`pg_dump -Fc` + Tar der Volumes `uploads`/`plugins`) auf dem
|
||
`backups`-Volume; Retention `BACKUP_RETENTION_DAYS` (Default 30,
|
||
Test/Int 7). Status in `status.json`, Fehler alarmieren per Mail
|
||
direkt via SMTP (bewusst nicht über die api — sie könnte das kaputte
|
||
Teil sein).
|
||
- **Zielbeschränkung (#192, ADR 0026):** Fernziele (rsync-Spiegel,
|
||
WebDAV) funktionieren nur gegen Hosts der **Deploy-Allowlist**
|
||
`BACKUP_ALLOWED_TARGETS`; eine leere Allowlist schaltet alle
|
||
Fernziele hart ab. Die Allowlist ist bewusst NICHT über die Admin-UI
|
||
änderbar (Rollentrennung, §6).
|
||
- **Restore:** `deploy/backup/restore.sh` fährt den Stack kontrolliert
|
||
herunter, spielt Dump + Volumes zurück und startet neu; Details und
|
||
Totalverlust-Szenario im Runbook.
|
||
- **Geprobter Restore:** ✅ erprobt — ein automatischer monatlicher
|
||
Restore-Drill (`drill-*`-Tag → `drill.yml`) stellt das jüngste
|
||
Prod-Set in einer Wegwerf-Umgebung wieder her und prüft Inhalte; das
|
||
Protokoll jedes Laufs steht als Kommentar an Issue #98.
|
||
Backups sind unverschlüsselt by design — Datenträgerschutz ist
|
||
Plattformsache (Abgrenzungserklärung).
|
||
|
||
## 4 Wartungsjobs (Scheduler)
|
||
|
||
Alle Jobs laufen in der api (in-app Scheduler, `jobs`-Tabelle), sind im
|
||
Site-Admin-Systempanel sichtbar und dort manuell auslösbar (auditiert
|
||
als `job.triggered`). Aktueller Bestand (10):
|
||
|
||
| Job | Rhythmus | Wirkung |
|
||
| -------------------------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
|
||
| `trash-purge` | täglich | endgültiges Löschen abgelaufener Papierkorb-Seiten **und** -Teiche (`trash.retentionDays`, #31/#193) |
|
||
| `orphan-file-sweep` | täglich | verwaiste Uploads entfernen (#194); trägt nachts auch den SHA-256-Backfill (#199) |
|
||
| `page-compaction` | stündlich | `page_updates`-Log in den Zustand mergen |
|
||
| `version-thinning` | täglich | automatische Versions-Snapshots ausdünnen |
|
||
| `audit-retention` | täglich | `audit_log` nach `audit.retentionDays` beschneiden (#196), Lücke selbst auditiert (`audit.pruned`) |
|
||
| `conversion-payload-prune` | täglich | Import-/Export-Payloads fertiger Jobs nullen (#233) |
|
||
| `mail-outbox-retention` | täglich | SENT/endgültig FAILED Outbox-Zeilen löschen (#234) |
|
||
| `data-export-purge` | stündlich | abgelaufene DSGVO-Datenexporte entfernen (#68) |
|
||
| `notification-digest` | alle 15 min (Versand nach Nutzer-Präferenz) | Benachrichtigungs-Digests versenden |
|
||
| `read-trail-maintenance` | täglich | Lesetrail-Partitionen vorausanlegen + `read_events` nach `readTrail.retentionDays` beschneiden (#224, auditiert `read_trail.pruned`) |
|
||
|
||
Der e2e-Zaun `apps/web/e2e/system.spec.ts` pinnt diese Zahl — ein
|
||
neuer Job ohne Handbuch-/Zaun-Anpassung wird rot.
|
||
|
||
## 5 Löschung und Vernichtung
|
||
|
||
Grundsatz: „Gelöscht" heißt in Dorfteich erst dann gelöscht, wenn alle
|
||
Kopien aus `60-sicherheitsdokumentation.md` §5 erreicht sind. Die
|
||
Tabelle nennt je Inhaltstyp, was die Löschung tut, welche Kopien sie
|
||
erreicht und was **stehen bleibt**.
|
||
|
||
| Vorgang | Wirkung | erreichte Kopien | Rückstände / Fristen |
|
||
| ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||
| Seite in den Papierkorb | Soft-Delete (`deleted_at`), aus Suchindex entfernt (#195) | Suchvektor sofort | Inhalt vollständig vorhanden, wiederherstellbar bis Purge |
|
||
| Seiten-Purge (automatisch nach `trash.retentionDays`, Default 30, oder manuell) | löscht Zustand, Update-Log, Content-Cache, Versionen, Kommentare, Attachments (Bytes + Quota), Watches; Kinder rücken auf | DB-Zeilen + `uploads`-Bytes | `page_links.target_slug` bleibt bewusst (#235, Restrisiko I-24); Backups/Spiegel bis Ablauf ihrer Retention; Export-/Endgeräte-Kopien organisatorisch |
|
||
| Teich-Purge (#193, automatisch/manuell, Site-Admin) | löscht alle Seiten samt Kaskade, Labels, Grants, Nutzungszähler, Plugin-Opt-ins, Conversion-Jobs, Files | wie oben, teichweit | wie oben |
|
||
| Nutzer löschen / DSGVO | Konto löschen bzw. Autorschaft pseudonymisieren (`user.pseudonymized`) | Identitätsdaten | von ihm erstellte Inhalte gehören dem Teich |
|
||
| Export-Payloads | `conversion-payload-prune` nullt `input`/`result` fertiger Jobs (Default 30 d) | DB | Job-Zeile bleibt für Status/Audit |
|
||
| Mail-Kopien | `mail-outbox-retention` löscht SENT/endgültig FAILED (Default 30 d) | DB | zugestellte Mails beim Empfänger (Restrisiko I-23) |
|
||
| Backup-Sets | Retention des Sidecars bzw. des Spiegels | `backups`-Volume, Spiegel | ein gelöschter Inhalt lebt maximal bis zum Ablauf der längsten Backup-Retention weiter — bei sofortigem Vernichtungsbedarf Sets manuell löschen (Host-Zugriff) und Spiegel bereinigen |
|
||
| Audit-Trail | `audit-retention` (Default 365 d) | DB | Metadaten, nie Inhalt |
|
||
|
||
**Sofortige Vernichtung einzelner Inhalte** (über die Fristen hinaus):
|
||
Seite manuell purgen (Papierkorb → endgültig löschen), danach auf dem
|
||
Host die Backup-Sets der Aufbewahrungskette löschen bzw. den Spiegel
|
||
bereinigen und Endgeräte-/Exportkopien organisatorisch einsammeln.
|
||
Belegstufe Purge-Pfade: ✅ erprobt (laufen täglich produktiv; Purge-
|
||
Semantik durch Tests gepinnt). Belegstufe „Backup-Kette manuell
|
||
vernichten": ⚠️ nicht geprobt.
|
||
|
||
**Außerbetriebnahme einer Instanz:** `docker compose down -v` entfernt
|
||
Container und **alle benannten Volumes** (`db-data`, `uploads`,
|
||
`plugins`, `secrets`, `backups`, Caddy-Volumes); anschließend Spiegel-
|
||
Bestände löschen und Host-Datenträger nach Betreiber-Vorgabe
|
||
vernichten — die physische Vernichtung ist Plattformsache
|
||
(Abgrenzungserklärung). Belegstufe: ✅ erprobt für den Stack-Teil (der
|
||
stillgelegte Alt-VPS wurde so zurückgebaut; Datenträger dort noch als
|
||
Rollback-Reserve vorhanden).
|
||
|
||
## 6 Rollentrennung
|
||
|
||
| Aufgabe | braucht |
|
||
| --------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
|
||
| Instanz-Settings, Nutzer-/Quota-Verwaltung, Plugins, Wartungsjobs anstoßen, Teich-Purge, Audit-Panel | **Site-Admin** (App-Rolle) |
|
||
| Deploy, `.env`/Compose ändern, Backup-Allowlist, Secrets-Volume, Restore, Backup-Sets vernichten, DB-Direktzugriff, Log-Collector | **Plattformzugriff** (Host) |
|
||
| Release nach Prod | Plattformzugriff + Freigabeprozess (Tag) |
|
||
|
||
Was ein Site-Admin **nicht** kann (bewusste Grenzen):
|
||
|
||
- die Backup-Zielliste ändern oder Fernziele aktivieren
|
||
(`BACKUP_ALLOWED_TARGETS` ist Deploy-Konfiguration, ADR 0026);
|
||
- Secrets lesen oder setzen, die im Secret-Store/der `.env` liegen
|
||
(die Settings-Tabelle trägt nie Secrets, security.md §Secrets);
|
||
- Deploy-/Composeänderungen, Image-Versionen, Migrationen auslösen;
|
||
- den Audit-Trail editieren (nur lesen; Retention läuft als Job und
|
||
protokolliert sich selbst);
|
||
- Backups herunterladen ist möglich (In-App-Restore-Pfad, #103), aber
|
||
ihre Vernichtung auf Host/Spiegel nicht.
|
||
|
||
Zu beachten: ein Site-Admin **liest** per Rollen-Bypass jeden Inhalt
|
||
der Instanz (permissions.md) — die Trennung „wer darf Inhalte sehen"
|
||
von „wer betreibt die Plattform" ist damit App-seitig bewusst NICHT
|
||
absolut; wo das nicht tragbar ist, ist es organisatorisch zu regeln
|
||
(Vier-Augen-Prinzip bei Vergabe der Site-Admin-Rolle). Der Lesetrail
|
||
für eingestufte Inhalte (M29, #222–#225) macht solche Zugriffe
|
||
nachvollziehbar.
|
||
|
||
## 7 Monitoring und Störung
|
||
|
||
Referenz: `deploy/monitoring.md`, `docs/architecture/operations.md`
|
||
§Health & monitoring.
|
||
|
||
- `GET /api/v1/readyz` prüft DB, Migrationen, Konverter, Renderer,
|
||
Backup-Status; `healthz` je Container. Externe Überwachung der
|
||
Referenzinstanzen: Uptime-Kuma mit Alarmierung.
|
||
- Logs: alle Dienste loggen JSON auf stdout (Docker json-file mit
|
||
Rotation); Audit-Ereignisse mit `msg`-Präfix `audit: ` und
|
||
`severity`-Feld — Weiterleitung an SIEM/Syslog übernimmt der
|
||
Collector des Betreibers (Katalog:
|
||
`docs/architecture/audit-events.md`, v1.1, mit
|
||
Kompatibilitätsversprechen).
|
||
- Integritätsalarm: `file.integrity_failed` (critical) = Download-Hash
|
||
≠ Upload-Hash → Objekt als manipuliert/korrupt behandeln, Datei aus
|
||
Backup-Set wiederherstellen (Runbook), erneut laden; der
|
||
Audit-Eintrag trägt beide Hashes.
|