# 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 |
| `denied` pull image `media-access-api` | Image distante invalide/inaccessible | Verifier `MEDIA_ACCESS_API_IMAGE` et dossier `media-access-api/` | Utiliser build local compose et relancer avec `--build` |
| Scripts tests KO sous WSL (`bash\r`) | Fins de ligne CRLF | `file tests/*.sh`, message `/usr/bin/env: bash\r` | Convertir en LF (`sed -i 's/\r$//' tests/*.sh`) et rejouer |
| 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.

## Cas pratique: erreur `denied` sur `media-access-api`
### Contexte
- Symptome: `docker compose up` echoue avec `Head https://ghcr.io/... denied`.

### Diagnostic
1. Verifier la variable: `grep MEDIA_ACCESS_API_IMAGE .env.dev`.
2. Verifier la presence du code local: `ls -la media-access-api`.
3. Verifier compose: `media-access-api` doit avoir un bloc `build`.

### Correction appliquee
1. Garder/mettre `MEDIA_ACCESS_API_IMAGE=local/media-access-api:dev`.
2. S'assurer que `media-access-api/` contient `Dockerfile` + code.
3. Relancer: `docker compose --env-file .env.dev -f compose.photoprism-secure.dev.yml up -d --build`.