fotospiel-app/docs/ops/operations-manual.md

title, sidebar_label, slug

title	sidebar_label	slug
Betriebshandbuch & Ops-Startseite	Betriebshandbuch	/

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.