132 lines
8.3 KiB
Markdown
132 lines
8.3 KiB
Markdown
---
|
||
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.
|