Installation

Zwei Wege: Produktivbetrieb via docker-compose (empfohlen) oder lokale Entwicklung mit nativen Diensten.

Produktion (docker-compose)

Voraussetzungen: Docker 24+, Docker Compose v2, eine Domain, die auf Ihren Host zeigt, offene Ports 80/443 sowie der offene LiveKit-UDP-Bereich (50000–50200/UDP, 7881/TCP).

git clone https://github.com/<...>/commentary
cd commentary
cp .env.production.example .env

Bearbeiten Sie .env:

DOMAIN — der öffentliche Hostname (z. B. commentary.example.com)
JWT_SECRET — generieren mit openssl rand -hex 64
ENCRYPTION_KEY — generieren mit openssl rand -hex 32 (32 Bytes für AES-256-GCM)
LIVEKIT_API_KEY / LIVEKIT_API_SECRET — generieren, dann in infra/livekit.yaml spiegeln
POSTGRES_PASSWORD, MINIO_ROOT_PASSWORD, REDIS_PASSWORD — generieren
LIVEKIT_WEBHOOK_HMAC_SECRET — generieren

Stack starten:

docker compose up -d
docker compose ps                  # all services healthy?
docker compose logs -f backend     # tail backend until "server ready"

Erstellen Sie den ersten Admin-Benutzer — siehe first-admin.md.

Caddy stellt beim ersten Aufruf von https://$DOMAIN/ automatisch ein Let’s-Encrypt-TLS-Zertifikat aus.

Lokale Entwicklung (native Dienste)

Voraussetzungen: macOS mit Homebrew, Go 1.26+, Node 20+, pnpm 9+, Bun (für Astro, falls Sie später an der Dokumentation arbeiten).

# Backing services
brew services start postgresql@17
brew services start redis
brew install minio/stable/minio && minio server ~/minio-data &

# DB
createdb commentary_dev
cd apps/server
cp .env.example .env                    # default dev values
go run ./cmd/api/migrate up             # or `goose -dir migrations postgres "$DATABASE_URL" up`
go run ./cmd/api                        # backend on :8095

# Frontends (separate terminals)
cd apps/studio && pnpm install && pnpm dev          # http://localhost:3030
cd apps/commentator && pnpm install && pnpm dev     # http://localhost:3031

# LiveKit local
livekit-server --config infra/livekit.dev.yaml &

Das Skript scripts/dev.sh kapselt all dies — pnpm dev im Repo-Root startet alles mit farbig präfixierten Logs und PID-Tracking. Details siehe Skript.

Schnelle End-to-End-Schleife

pnpm dev              # brings up infra check + backend + studio + commentator + LiveKit
pnpm seed             # bootstraps a demo event + commentator + invite, prints the URLs
# → click the printed invite URL to test commentator kiosk
# → in studio at http://localhost:3030, use the "Dev only — Connexion rapide"
#   panel (DevQuickLogin component, tree-shaken in prod) to login instantly
pnpm stop             # clean shutdown (preserves DB/Redis volumes)

scripts/seed-dev.sh sendet Anfragen an die laufende Backend-API, um die Demo-Daten anzulegen, und gibt die Studio- und Kommentator-URLs zum Kopieren/Einfügen aus. Standard-Admin: [email protected] / DevTest-12345! (angelegt durch den Bootstrap-Schritt; das Passwort muss ≥ 13 Zeichen lang sein).

E2E-Tests mit Fake-Media-Streams (Playwright)

Die Playwright-Tests für den v1.2-Videoflow benötigen Chrome, das getUserMedia ohne Abfrage gewährt und synthetisches Video/Audio liefert. Die Datei playwright.config.ts des Repos setzt bereits:

launchOptions: {
  args: ['--use-fake-ui-for-media-stream', '--use-fake-device-for-media-stream'],
}

Keine weitere Einrichtung nötig. Um nur die v1.2-Video-Spec auszuführen:

pnpm test:e2e --grep "live-video"

Studio-Publishing (PGM + Talkback)

Seit v1.6 publiziert das Studio PGM-Video + -Audio sowie das Talkback-Intercom-Audio direkt aus dem Browser — kein OBS, kein WHIP. Siehe usage.md Abschnitt 7 für den Operator-Workflow.

Voraussetzungen

Ein moderner Chromium-basierter Browser auf dem Studio-Rechner (Chrome, Edge, Brave) für zuverlässige getUserMedia-Geräteauswahl. Firefox funktioniert, unterstützt aber kein elementbezogenes Sink-Routing.
Upstream-Bandbreite des Studios: ≥ 5 Mbps empfohlen (PGM 1080p30 ~3 Mbps + Talkback-Audio + Kommentator-Subscribe). Vor jedem Produktiv-Event mit speedtest-cli testen:
Terminal-Fenster
```
brew install speedtest-cli && speedtest
```

Historische Anmerkung: v1.1–v1.5 versuchten OBS-WHIP-Ingest in LiveKit. Das eingesetzte LK v1.7.2 bietet keinen /whip-Endpunkt, daher hat dieser Weg in der Produktion nie funktioniert. v1.6 hat ihn zugunsten des In-Browser-Publishings entfernt.

Weiter

→ first-admin.md, um Ihr erstes Admin-Konto anzulegen.