--- 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. - **Roadmap & Epics** - Aktive Epics und offene Arbeitspakete werden in bd gepflegt (`bd list --status=open`, `bd ready`). - **Changes & Retro-Notizen** - Lessons Learned, Follow-ups und Incident-Maßnahmen werden als bd-Issues oder Issue-Notizen festgehalten. Als Betreiber lohnt es sich, vor größeren Deployments die offenen bd-Issues zu prüfen, 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.