Installation

Deux voies : production via docker-compose (recommandé), ou développement local avec services natifs.

Production (docker-compose)

Prérequis : Docker 24+, Docker Compose v2, un domaine pointant vers votre hôte, ports 80/443 ouverts + plage UDP LiveKit (50000–50200/UDP, 7881/TCP) ouverte.

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

Éditez .env :

DOMAIN — le nom d’hôte public (p. ex. commentary.example.com)
JWT_SECRET — à générer avec openssl rand -hex 64
ENCRYPTION_KEY — à générer avec openssl rand -hex 32 (32 octets pour AES-256-GCM)
LIVEKIT_API_KEY / LIVEKIT_API_SECRET — à générer, puis recopier dans infra/livekit.yaml
POSTGRES_PASSWORD, MINIO_ROOT_PASSWORD, REDIS_PASSWORD — à générer
LIVEKIT_WEBHOOK_HMAC_SECRET — à générer

Démarrez la stack :

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

Créez le premier utilisateur admin — voir first-admin.md.

Caddy provisionne automatiquement le certificat TLS Let’s Encrypt à la première requête vers https://$DOMAIN/.

Développement local (services natifs)

Prérequis : macOS avec Homebrew, Go 1.26+, Node 20+, pnpm 9+, Bun (pour Astro si vous touchez aux docs plus tard).

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

Le script scripts/dev.sh enveloppe tout cela — pnpm dev depuis la racine du repo démarre l’ensemble avec des logs colorés préfixés et un suivi des PID. Voir le script pour les détails.

Boucle end-to-end rapide

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 envoie des requêtes à l’API du backend en cours d’exécution pour créer les données de démo et affiche les URL du studio et du commentateur prêtes à copier/coller. Admin par défaut : [email protected] / DevTest-12345! (créé par l’étape de bootstrap ; le mot de passe doit faire ≥ 13 caractères).

Tests E2E avec flux média factices (Playwright)

Les tests Playwright du flux vidéo v1.2 nécessitent que Chrome accorde getUserMedia sans invite et serve de la vidéo/audio synthétique. Le playwright.config.ts du repo définit déjà :

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

Aucune configuration supplémentaire requise. Pour exécuter uniquement la spec vidéo v1.2 :

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

Publication depuis le studio (PGM + Talkback)

Depuis la v1.6, le studio publie la vidéo + l’audio PGM (retour programme) et l’audio d’intercom talkback directement depuis le navigateur — pas d’OBS, pas de WHIP. Voir usage.md section 7 pour le workflow opérateur.

Prérequis

Un navigateur moderne basé sur Chromium sur la machine du studio (Chrome, Edge, Brave) pour une sélection fiable des périphériques via getUserMedia. Firefox fonctionne mais ne propose pas le routage de sortie par élément.
Bande passante montante du studio : ≥ 5 Mbps recommandés (PGM 1080p30 ~3 Mbps + audio talkback + souscription commentateur). Testez avec speedtest-cli avant chaque événement de production :
Fenêtre de terminal
```
brew install speedtest-cli && speedtest
```

Note historique : les versions v1.1–v1.5 ont tenté l’ingest OBS WHIP dans LiveKit. La version LK v1.7.2 déployée n’expose pas d’endpoint /whip, donc ce chemin n’a jamais fonctionné en production. La v1.6 l’a abandonné au profit de la publication depuis le navigateur.

Suite

→ first-admin.md pour créer votre premier compte admin.