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

## 1.1 Superadmin‑Kontrollfläche & Zugriffs‑Matrix

Die Superadmin‑Konsole ist für operative Kontrolle und Eskalation gedacht – nicht für tägliche Tenant‑Arbeit. Ziel ist eine minimale, aber vollständige Kontrollfläche.

**Minimaler Control Surface (Superadmin)**
- **Tenant‑Lifecycle & Limits:** Aktivieren/Sperren, Grace‑Periode, Löschung/Anonymisierung, Limits (Fotos/Event, Storage), Audit‑Timeline.
- **Commercial & Billing:** Pakete/Addons, Tenant‑Pakete, Käufe/History, Gutscheine/Coupons.
- **Event‑Oversight:** Events/Fotos global, Moderations‑Queues, Tenant‑Feedback.
- **Plattform & Compliance:** Legal Pages, Datenexporte, Audit‑Log.
- **Infra & Storage:** Storage Targets, Photobooth Settings, Deployments/Logs.

**Zugriffs‑Matrix (Soll)**

| Bereich | Superadmin | Tenant‑Admin | Gast |
| --- | --- | --- | --- |
| Tenant‑Lifecycle & Limits | RW | R (own) | – |
| Tenant‑Pakete & Billing | RW | R (own) | – |
| Events/Photos (global) | RW | RW (own) | R/W (event scope) |
| Moderation/Feedback | RW | RW (own) | – |
| Tasks/Emotions/Event‑Types | RW | RW (own) | R (event scope) |
| Users (Platform) | RW | R (own) | – |
| Legal/Content | RW | R | R (public) |
| Storage/Photobooth/Infra | RW | R | – |
| Audit‑Log (Admin‑Aktionen) | R | – | – |

**Nicht‑Ziele**
- Superadmin ersetzt keine Tenant‑Admins für Tagesgeschäft, nur Eskalation.
- Kein zusätzliches Tracking/PII‑Logging ohne Privacy‑Update.
- Keine Infrastruktur‑Mutation ohne explizite Freigabe.

## 1.2 Superadmin‑Roadmap (geplante Seiten & Zweck)

Diese Seiten sollen praktische Steuerung über Tenant‑Admins und die Guest‑Experience geben, ohne ins Tagesgeschäft abzurutschen.

- **Moderation‑Queue (Guest‑Content):** Flagged Fotos/Feedback sammeln, bulk hide/delete/resolve, sauberes Audit.
- **Guest‑Policy‑Settings:** Default‑Toggles (Downloads/Sharing), Rate‑Limits, Retention‑Defaults, damit neue Events konsistent starten.
- **Ops‑Health‑Dashboard:** Queue‑Backlog, failed jobs, Storage‑Schwellen, Upload‑Pipeline‑Health auf einen Blick.
- **Compliance‑Tools:** DSGVO‑Export‑Requests und Retention‑Overrides pro Tenant/Event.
- **Superadmin‑Audit‑Log:** Jede Admin‑Aktion nachvollziehbar (ohne PII‑Payloads).
- **Tenant‑Announcements:** Zielgerichtete Hinweise/Release‑Notes an Tenant‑Admins, inkl. Zeitplanung.
- **Integrations‑Health:** Status‑Board für Paddle/RevenueCat/Webhooks inkl. Störungen.

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