Dépannage

Problèmes courants et comment les diagnostiquer.

/readyz retourne 503

Le backend se signale comme non sain. Vérifiez ce qui échoue :

docker compose ps
docker compose logs backend | tail -50
docker compose exec backend wget -qO- http://localhost:8095/readyz

/readyz sonde Postgres + Redis + LiveKit. La réponse JSON indique quelle dépendance est en panne. Le plus souvent :

• Postgres pas encore prêt (attendez 10–20 s après docker compose up)
• Mot de passe Redis différent entre .env et le container
• Signalisation LiveKit injoignable (vérifiez que la variable d’env LIVEKIT_HOST se résout)

LiveKit connection refused / échec WebSocket

docker compose logs livekit | tail -30

Deux causes courantes :

1. API key/secret non concordants. infra/livekit.yaml contient keys: { <KEY>: <SECRET> } et le backend lit LIVEKIT_API_KEY / LIVEKIT_API_SECRET depuis .env. Ils doivent correspondre exactement. En cas de doute, régénérez les deux côtés.
2. Ports UDP bloqués. Les médias WebRTC transitent par UDP 50000–50200 (configurable dans infra/livekit.yaml). Sur un hôte derrière un pare-feu, ces ports doivent être ouverts. Le fallback TCP utilise le port 7881 — plus lent, mais fonctionne à travers les réseaux restrictifs.

Cookie non posé après la connexion

Symptôme : l’API de connexion retourne 200 OK mais le navigateur renvoie immédiatement vers /login. Le cookie de session n’a pas été accepté.

Causes :

• La variable d’env DOMAIN ne correspond pas à l’hôte que vous interrogez (cookie domain mismatch)
• Vous accédez en HTTP, pas en HTTPS — les cookies Secure exigent TLS dans les navigateurs modernes
• Vous êtes derrière un proxy qui supprime Set-Cookie — vérifiez les logs Caddy

docker compose logs caddy | grep -i cookie

401 Unauthorized sur les routes protégées

Les access tokens ont un TTL de 15 minutes. À l’expiration, le studio se rafraîchit silencieusement à la requête suivante via le refresh token opaque (30 jours glissants). Si vous voyez des 401 en rafale :

• Refresh token également expiré → l’utilisateur doit se reconnecter
• Décalage d’horloge entre client et serveur > 30 s → corrigez NTP sur l’hôte
• Refresh token révoqué (déconnexion depuis un autre appareil) → reconnexion

Échec d’une migration Postgres

docker compose exec backend goose -dir /app/migrations \
  postgres "$DATABASE_URL" status

Si goose est désynchronisé (une migration a été appliquée manuellement, ou une exécution précédente a planté en cours de migration), vous pouvez :

# See the state
goose -dir migrations postgres "$DATABASE_URL" status

# Force to a known version (CAREFUL — does not run the SQL)
goose -dir migrations postgres "$DATABASE_URL" version
goose -dir migrations postgres "$DATABASE_URL" up-by-one

Pour une base de dev complètement cassée, supprimez et recréez :

docker compose down postgres
docker volume rm commentary_postgres-data
docker compose up -d postgres backend

Le kiosk du commentateur affiche « pas de permission » pour le micro

Le navigateur a bloqué l’accès au micro. Le kiosk est réservé à Chrome (il utilise AudioContext.sinkId pour le routage des périphériques de sortie). Dans Chrome :

1. Cliquez sur l’icône cadenas dans la barre d’adresse
2. Paramètres du site → Microphone → Autoriser
3. Rechargez la page

Sur macOS / Windows, vérifiez aussi la permission micro au niveau de l’OS pour Chrome.

Caddy n’obtient pas de certificat TLS

docker compose logs caddy | grep -i acme

Problèmes typiques :

• Port 80 bloqué ou déjà utilisé par un autre service (Caddy a besoin du :80 pour HTTP-01)
• Le DNS n’a pas encore propagé — attendez 5 minutes puis docker compose restart caddy
• Limite de débit Let’s Encrypt atteinte (5 certificats par domaine et par semaine) — attendez, ou utilisez temporairement l’endpoint de staging via acme_ca https://acme-staging-v02.api.letsencrypt.org/directory dans le Caddyfile

Toujours bloqué ?

Ouvrez une issue avec la sortie de :

docker compose ps
docker compose logs --tail=100 backend caddy livekit

Supprimez tout secret avant de publier.