---
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.
