Installation

Two paths: production via docker-compose (recommended), or local dev with native services.

Production (docker-compose)

Prerequisites: Docker 24+, Docker Compose v2, a domain pointing to your host, ports 80/443 open + LiveKit UDP range (50000–50200/UDP, 7881/TCP) open.

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

Edit .env:

DOMAIN — the public hostname (e.g. commentary.example.com)
JWT_SECRET — generate with openssl rand -hex 64
ENCRYPTION_KEY — generate with openssl rand -hex 32 (32 bytes for AES-256-GCM)
LIVEKIT_API_KEY / LIVEKIT_API_SECRET — generate, then mirror into infra/livekit.yaml
POSTGRES_PASSWORD, MINIO_ROOT_PASSWORD, REDIS_PASSWORD — generate
LIVEKIT_WEBHOOK_HMAC_SECRET — generate

Start the stack:

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

Bootstrap the first admin user — see first-admin.md.

Caddy will provision Let’s Encrypt TLS automatically on first request to https://$DOMAIN/.

Local dev (native services)

Prerequisites: macOS with Homebrew, Go 1.26+, Node 20+, pnpm 9+, Bun (for Astro if you touch docs later).

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

The scripts/dev.sh script wraps all of this — pnpm dev from repo root brings everything up with prefixed colored logs and PID tracking. See the script for details.

Fast end-to-end loop

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 posts to the running backend API to create the demo data and prints the studio + commentator URLs ready to copy/paste. Default admin: [email protected] / DevTest-12345! (created by the bootstrap step ; password must be ≥ 13 chars).

E2E tests with fake media streams (Playwright)

Playwright tests for the v1.2 video flow need Chrome to grant getUserMedia without a prompt and serve synthetic video/audio. The repo’s playwright.config.ts already sets:

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

No additional setup required. To run only the v1.2 video spec:

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

Studio publishing (PGM + Talkback)

Since v1.6 the studio publishes PGM video + audio and Talkback intercom audio directly from the browser — no OBS, no WHIP. See usage.md section 7 for the operator workflow.

Prerequisites

A modern Chromium-based browser on the studio machine (Chrome, Edge, Brave) for reliable getUserMedia device picking. Firefox works but lacks per-element sink routing.
Studio upstream bandwidth : ≥ 5 Mbps recommended (PGM 1080p30 ~3 Mbps + talkback audio + commentator subscribe). Test with speedtest-cli before each prod event :
Terminal window
```
brew install speedtest-cli && speedtest
```

Historical note : v1.1–v1.5 attempted OBS WHIP ingest into LiveKit. The deployed LK v1.7.2 ships no /whip endpoint, so the path never worked in prod. v1.6 dropped it in favour of in-browser publish.

→ first-admin.md to create your first admin account.