further rework to the documentation

2025-11-20 12:31:21 +01:00
parent 6afa44d947
commit 9afcaa7836
90 changed files with 1721 additions and 29 deletions
--- a/docs/ops/operations-manual.md
+++ b/docs/ops/operations-manual.md
@@ -0,0 +1,131 @@
+---
+title: Betriebshandbuch & Ops-Startseite
+sidebar_label: Betriebshandbuch
+slug: /
+---
+
+Willkommen im Betriebshandbuch von Fotospiel. Dieses Dokument ist der Einstiegspunkt für alle, die die Plattform betreiben: Infrastruktur‑Ops, On‑Call, Support mit erweiterten Rechten und Produkt‑Owner, die Auswirkungen von Änderungen verstehen möchten.
+
+Ziel ist, dass du von hier aus schnell zu den relevanten Runbooks und Referenzen springen kannst.
+
+## 1. Systemübersicht & Verantwortlichkeiten
+
+- **Rollen & Verantwortlichkeiten**
+  - Wer ist für welche Ebene zuständig? (App‑Verfügbarkeit, Infrastruktur, Sicherheit, Abrechnung, Support.)
+  - Empfehlung: definiere mindestens _On‑Call_, _Plattform‑Ops_ und _Support (2nd Level)_ als feste Rollen – diese Seite ist für alle drei.
+- **Systemlandschaft (High‑Level)**
+  - Laravel App + Nginx + Redis + MySQL.
+  - Async‑Pipeline: Queues (`default`, `media-storage`, `media-security`, `notifications`) und Horizon.
+  - Satelliten: Photobooth‑FTP + Control‑Service, Docs‑Site (`/internal-docs`), Monitoring/Dokploy.
+  - Externe Dienste: Paddle (Billing), RevenueCat (Mobile‑Abos), E‑Mail Provider, Logging/Monitoring (Loki/Grafana o.ä.).
+
+> TODO: Ergänze ein Architekturdiagramm aus Sicht des Betriebs (z.B. als PNG oder PlantUML) und verlinke es hier.
+
+## 2. Deployments & Infrastruktur
+
+Diese Kapitel erklären, wie die Plattform in Docker/Dokploy betrieben wird.
+
+- **Docker-Deployment (Compose‑Stack)**
+  - `docs/ops/deployment/docker.md` – Referenz für `docker-compose.yml`, Services, Volumes, Migrations und Scheduler‑Setup.
+- **Dokploy-Deployment (PaaS)**
+  - `docs/ops/deployment/dokploy.md` – Wie die gleichen Services als Dokploy‑Compose‑Stacks betrieben werden, inkl. SuperAdmin‑Integration.
+- **Join-Token-Analytics & Public API**
+  - `docs/ops/deployment/join-token-analytics.md` – Konfiguration der Analytics‑Pfade für Join‑Tokens.
+  - `docs/ops/deployment/public-api-incident-playbook.md` – Runbook für Public‑API‑Störungen (Rate‑Limits, Abuse, Outages).
+- **Lokale Podman/Dev-URLs**
+  - `docs/ops/deployment/lokale-podman-adressen.md` – Übersicht über lokale Services/Ports bei Podman‑Setups.
+
+Fragen zur Infrastruktur (Netzwerk, TLS, DNS, Backups) sollten immer zuerst gegen diese Dokumente geprüft werden.
+
+## 3. Queues, Storage & Medien-Pipeline
+
+Fotos sind das Herz des Produkts – entsprechend wichtig ist ein klarer Blick auf die Medien‑Pipeline.
+
+- **Queues & Worker**
+  - `docs/ops/queue-workers.md` – Wie die Worker‑Container (`queue`, `media-storage-worker`, `media-security-worker`, `notifications`) gestartet, skaliert und überwacht werden.
+- **Media Storage & Archivierung**
+  - `docs/ops/media-storage-spec.md` – Detaillierte Beschreibung, wie Uploads in den „hot“‑Storage laufen, wie `event_media_assets` gepflegt werden und wie Archive‑Jobs funktionieren.
+- **Upload-Gesundheit & Notifications**
+  - `docs/ops/guest-notification-ops.md` – Runbook für das Notification‑Center, Push‑Registrierung und Upload‑Health‑Alerts.
+
+> TODO: Ergänze ein zentrales „Storage & Queues Monitoring“-Kapitel mit konkreten Schwellenwerten und Alarmierung (z.B. Einbindung von Horizon, Redis‑Monitoring, Log-Channels).
+
+## 4. Photobooth-Pipeline
+
+Die Photobooth‑Integration hat eigene Betriebsanforderungen:
+
+- `docs/ops/photobooth/README.md` – Überblick über Photobooth‑Setup und Datenfluss.
+- `docs/ops/photobooth/control_service.md` – Steuer‑API (User‑Provisionierung, Credentials, Rate‑Limits).
+- `docs/ops/photobooth/ops_playbook.md` – Operatives Playbook für Aktivierung, Fehleranalyse und Incident‑Response rund um Photobooth‑Uploads.
+
+> Prüfe vor großen Events mit gebuchten Photobooths diese Playbooks und stelle sicher, dass Volumes, Credentials und Scheduler korrekt konfiguriert sind.
+
+## 5. Störungs- & Incident-Runbooks
+
+Die folgenden Dokumente sind deine erste Anlaufstelle im Incident‑Fall:
+
+- **Major Incidents & Eskalation**
+  - `docs/ops/incidents-major.md` – genereller Rahmen (SEV‑Levels, Triage, Kommunikation, Postmortems) und Verweise auf die spezifischen Runbooks unten.
+- **Public API Störungen**
+  - `docs/ops/deployment/public-api-incident-playbook.md` – Schritt‑für‑Schritt‑Plan bei Missbrauch, Fehlerspitzen oder Ausfällen der öffentlichen APIs.
+- **Upload-/Medien-Probleme**
+  - `docs/ops/media-storage-spec.md` – Referenz, welche Queues/Jobs beteiligt sind und wie man Fehlerzustände erkennt (z.B. lange „pending“-Assets, gescheiterte Archivierung).
+  - `docs/ops/guest-notification-ops.md` – Upload‑Alerts und Gastbenachrichtigungen.
+- **Photobooth-Incidents**
+  - `docs/ops/photobooth/ops_playbook.md` – Vorgehen bei ausfallendem FTP, Ingest‑Fehlern oder Sicherheitsvorfällen (Credentials).
+
+Zusätzlich gibt es kurze „How‑to“-Runbooks für häufige Supportfälle:
+
+- `docs/ops/howto-tenant-package-not-active.md` – Zahlung erfolgreich, Paket nicht aktiv.
+- `docs/ops/howto-guest-upload-failing.md` – Gäste können nicht hochladen.
+- `docs/ops/howto-photobooth-no-photos.md` – Photobooth‑Uploads landen nicht im Event.
+- `docs/ops/howto-dsgvo-delete-photo.md` – DSGVO‑Löschung eines konkreten Fotos.
+
+> TODO: Ergänze ein allgemeines „Major Incident“‑Kapitel (SEV‑1/2 Definition, Kommunikationskanäle, Vorlagen) und verlinke es hier.
+
+## 6. Prozesse, Roadmap & Änderungen
+
+Der Betreiber muss wissen, welche größeren Änderungen anstehen oder kürzlich live gegangen sind.
+
+- **Prozess-Hub**
+  - `docs/process/README.md` – erklärt Struktur von `changes/`, `todo/` und `roadmap.md`.
+- **Roadmap & Epics**
+  - `docs/process/roadmap.md` – Überblick über aktive Epics (z.B. Security Hardening, Paddle‑Migration, Streaming‑Uploads) und kürzlich abgeschlossene Themen.
+  - `docs/process/todo/security-hardening-epic.md` – Security‑Hardening‑Plan mit Bezug zu Ops (Signierte URLs, AV/EXIF, Monitoring‑Workstreams).
+  - Paddle‑Themen: `docs/process/todo/paddle-migration.md`, `docs/process/todo/paddle-catalog-sync.md`.
+- **Changes & Retro-Notizen**
+  - `docs/process/changes/*` – Session‑Notizen, Refactor‑Pläne und Lessons Learned (z.B. Checkout‑Refactor, Registrierung‑Fixes).
+
+Als Betreiber lohnt es sich, bei größeren Deployments kurz in `roadmap.md` und den passenden `changes/*` zu schauen, um Seiteneffekte zu antizipieren.
+
+## 7. Tests, Qualität & Releases
+
+Stabile Releases sind Grundvoraussetzung für ruhigen Betrieb:
+
+- **E2E-Tests & Qualität**
+  - `docs/testing/e2e.md` – beschreibt, welche End‑to‑End‑Tests existieren und wie sie als Smoke‑Suite für Releases verwendet werden können.
+- **Release-Prozess (Entwurf)**
+  - `docs/ops/releases.md` – Checkliste für CI‑Pipelines, Staging‑Deploy, Prod‑Rollout, Smoke‑Tests und Rollback‑Überlegungen.
+
+## 8. Nächste Schritte für das Betriebshandbuch
+
+Die folgenden Kapitel sind als eigenständige Runbooks angelegt und sollten mit der Zeit weiter gefüllt werden:
+
+- **Rollen & On-Call-Handbuch**
+  - `docs/ops/oncall-roles.md` – definiert Platform‑Ops, On‑Call, Support und Produktrollen sowie Eskalationswege.
+- **On-Call Cheat Sheet**
+  - `docs/ops/oncall-cheatsheet.md` – schnelle Übersicht über wichtige Kommandos, Logs und Dashboards für Incidents.
+- **Support & Eskalation**
+  - `docs/ops/support-escalation-guide.md` – beschreibt, welche Informationen Support von Kunden einsammeln sollte, bevor an Ops eskaliert wird.
+- **Backup & Restore / Disaster Recovery**
+  - `docs/ops/backup-restore.md` – Was gesichert werden muss, Restore‑Szenarien und DR‑Übungen.
+- **DSGVO & Compliance-Operationen**
+  - `docs/ops/compliance-dsgvo-ops.md` – Praktische Abläufe für Auskunfts‑/Löschanfragen, Retention und Dokumentation.
+- **Billing & Zahlungs-Operationen**
+  - `docs/ops/billing-ops.md` – Umgang mit Zahlungsproblemen, Webhook‑Fehlern und Paket‑Inkonsistenzen.
+- **Monitoring & Observability**
+  - `docs/ops/monitoring-observability.md` – Welche Signale, Metriken und Alerts es geben sollte.
+- **Architektur-Diagramme**
+  - `docs/ops/diagrams.md` – Mermaid‑Diagramme für Media‑Pipeline und Checkout/Billing‑Flow.
+
+Das Betriebshandbuch bleibt damit ein lebendes Dokument. Neue Runbooks sollten unter `docs/ops/` entstehen und hier verlinkt werden, damit Operatoren einen klaren Einstiegspunkt behalten.