1 files changed, 140 insertions, 0 deletions
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
new file mode 100644
index 0000000..58d72a2
--- /dev/null
+++ b/docs/TROUBLESHOOTING.md
@@ -0,0 +1,140 @@
+# TROUBLESHOOTING
+
+## Objectif
+Fournir une procedure de diagnostic et resolution rapide des incidents.
+
+## Symptomes frequents
+- Echec connexion Keycloak
+- Refus d'acces media (403)
+- Erreur token/JWT
+- Indisponibilite stockage media
+- Decalage horaire VM / erreurs de validation temporelle (token, TLS)
+
+## Checklist de diagnostic initial
+1. Identifier l'environnement impacte.
+2. Verifier l'etat des services.
+3. Consulter les logs applicatifs et IAM.
+4. Reproduire le probleme avec un cas minimal.
+
+## Checklist express: `photos.arauco.online` inaccessible
+Executer dans cet ordre pour isoler rapidement le point de blocage.
+
+```bash
+# 1) DNS: le domaine doit pointer vers l'IP de araucaria (Caddy)
+dig +short photos.arauco.online
+
+# 2) Reachability 443 depuis client
+curl -vkI https://photos.arauco.online
+
+# 3) Caddy actif et sans erreur de config sur araucaria
+sudo caddy validate --config /etc/caddy/Caddyfile && sudo systemctl status caddy --no-pager
+
+# 4) Port 443 ecoute sur araucaria
+sudo ss -lntp | grep :443
+
+# 5) Backend viewer-bff reachable depuis araucaria
+curl -I http://192.168.99.23:8082/health
+```
+
+Interpretation rapide:
+- (1) vide ou mauvaise IP: corriger dnsmasq.
+- (2) timeout/refused: route/firewall/Caddy KO.
+- (3) echec validate: corriger Caddyfile.
+- (4) rien sur 443: Caddy non demarre ou bind incorrect.
+- (5) backend KO: service viewer-bff/route VM a corriger.
+
+## Matrice cause probable -> action
+| Symptom | Cause probable | Verification | Action corrective |
+| --- | --- | --- | --- |
+| 401/403 | Role/groupe manquant | Inspecter claims JWT | Corriger mapping roles/groupes |
+| Timeout | Service indisponible | Healthcheck et reseau | Redemarrer service / corriger reseau |
+| Token invalide | Mauvaise config OIDC | Verifier issuer/audience | Corriger configuration client |
+| 401 sur viewer-bff | Token absent/non transfere | Verifier header Authorization | Rejouer avec Bearer token valide |
+| Heure incoherente | NTP non synchronise | `timedatectl`, `chronyc tracking` | Configurer chrony vers `araucaria` |
+| Nom DNS local non resolu | Record dnsmasq absent/invalide | `dig +short <host>.arauco.online` | Corriger fichier dnsmasq puis restart service |
+| HTTPS KO via domaine | Caddy non charge / vhost invalide | `caddy validate`, `journalctl -u caddy` | Corriger Caddyfile puis reload Caddy |
+
+## Procedure de resolution
+1. Isoler la cause racine.
+2. Appliquer la correction minimale.
+3. Valider la resolution.
+4. Documenter l'incident et la correction.
+
+## Escalade
+- Niveau 1:
+- Niveau 2:
+- Niveau 3:
+
+## Post-mortem court
+- Impact:
+- Cause racine:
+- Correctif:
+- Prevention:
+
+## Template d'incident
+- Utiliser `docs/TEMPLATE_INCIDENT.md` pour chaque incident.
+- Copier le template, le remplir, puis referencer l'entree dans `docs/CHANGELOG_OPERATIONS.md`.
+
+## Historique incidents resolus
+- Date:
+- Incident:
+- Resolution:
+
+## Cas pratique: erreur 403 sur media protege
+### Contexte
+- Date: 2026-03-07
+- Environnement: dev
+- Symptome: utilisateur authentifie, mais acces refuse sur `GET /media/{id}` (403)
+
+### Diagnostic
+1. Token JWT decode: role `media_reader` absent.
+2. Mapping Keycloak verifie: groupe `consultants` non mappe vers role applicatif.
+3. Logs API confirment: `missing required role media_reader`.
+
+### Correction appliquee
+1. Ajouter mapper de groupe dans Keycloak (`consultants` -> `media_reader`).
+2. Forcer reconnexion utilisateur pour emettre un nouveau token.
+3. Rejouer le test d'acces sur le meme media.
+
+### Validation
+- Avant correctif: 403 confirme.
+- Apres correctif: 200 confirme.
+- Aucun impact detecte sur les autres roles.
+
+### Prevention
+- Ajouter test automatique de non-regression RBAC (cas 200/403).
+- Exiger verification des mappers lors de creation de nouveau groupe.
+
+## Cas pratique: DNS local medias non resolu
+### Contexte
+- Symptome: `photos.arauco.online` ne repond pas ou resolve une mauvaise IP.
+
+### Diagnostic
+1. Verifier fichier `/etc/dnsmasq.d/20-medias-araucaria.conf`.
+2. Verifier syntaxe: `sudo dnsmasq --test`.
+3. Verifier service: `sudo systemctl status dnsmasq --no-pager`.
+4. Verifier resolution: `dig +short photos.arauco.online`.
+
+### Correction appliquee
+1. Corriger les records `host-record` vers l'IP de `araucaria` (Caddy).
+2. Redemarrer `dnsmasq`.
+3. Vider cache DNS poste client si necessaire.
+
+### Validation
+- `dig +short photos.arauco.online` retourne l'IP de `araucaria`.
+- Acces URL de service valide.
+
+## Cas pratique: domaine HTTPS indisponible via Caddy
+### Contexte
+- Symptome: `https://photos.arauco.online` indisponible alors que le service local repond.
+
+### Diagnostic
+1. Verifier Caddy: `sudo caddy validate --config /etc/caddy/Caddyfile`.
+2. Verifier etat: `sudo systemctl status caddy --no-pager`.
+3. Verifier logs: `sudo journalctl -u caddy -n 100 --no-pager`.
+4. Verifier backend: `curl -I http://192.168.99.23:8082/health`.
+
+### Correction appliquee
+1. Corriger le bloc de vhost dans Caddyfile.
+2. Recharger: `sudo systemctl reload caddy`.
+3. Rejouer le test HTTPS.