# RUNBOOK — Edge Traefik (routing + SSO Authelia)
> Objectif : comprendre et diagnostiquer rapidement qui route quoi, et pourquoi staging/live peuvent diverger.

## 0) Portée
Edge Traefik route plusieurs hosts vers des backends locaux (127.0.0.1:*), avec Auth via Authelia.

Répertoire :
- `/volume2/docker/edge/config/dynamic/`

Port d’entrée edge :
- `http://127.0.0.1:18080/` (entryPoint `web`)
- Les hosts publics pointent vers cet edge.

## 1) Fichiers dynamiques (canon)
### 00-smoke.yml
- route `/__smoke` vers le service `smoke_svc` → `127.0.0.1:18081`

### 10-core.yml
- définit les middlewares :
  - `sanitize-remote`
  - `authelia` (forwardAuth vers 9091)
  - `chain-auth` (chain sanitize-remote + authelia)

### 20-archicratie-backend.yml
- définit service `archicratie_web` → `127.0.0.1:8082` (live upstream)

### 21-archicratie-staging.yml
- route staging host vers `127.0.0.1:8081` (staging upstream)
- applique middlewares `diag-staging@file` et `chain-auth@file`
- IMPORTANT : `diag-staging@file` doit exister

### 22-archicratie-authinfo-staging.yml
- route `/ _auth /` sur staging vers `whoami@file`
- applique `diag-staging-authinfo@file` + `chain-auth@file`
- IMPORTANT : `diag-staging-authinfo@file` doit exister

### 90-overlay-staging-fix.yml (overlay de diagnostic + fallback)
Rôle :
- **fournir** les middlewares manquants (`diag-staging`, `diag-staging-authinfo`)
- optionnel : fallback route si 21/22 sont cassés
- injecter un header `X-Archi-Router` pour identifier le routeur utilisé

### 92-overlay-live-fix.yml
- route live host `archicratie.trans-hands.synology.me` → `archicratie_web@file` (8082)
- route `/ _auth/whoami` → `whoami@file` (18081)

## 2) Diagnostiquer rapidement : quel routeur répond ?
### 2.1 Test “host header” (sans UI)
# en bash :

curl -sSI -H 'Host: staging.archicratie.trans-hands.synology.me' http://127.0.0.1:18080/ \
 | grep -iE 'HTTP/|location:|x-archi-router' | head -n 30

curl -sSI -H 'Host: staging.archicratie.trans-hands.synology.me' http://127.0.0.1:18080/_auth/whoami \
 | grep -iE 'HTTP/|location:|x-archi-router' | head -n 30

# Interprétation :

X-Archi-Router: staging@21 → routeur 21-archicratie-staging.yml OK

X-Archi-Router: staging-authinfo@22 → routeur authinfo OK

Si tu vois staging-fallback@90 → tu es tombé sur le fallback 90 (donc 21/22 potentiellement invalides)

### 2.2 Vérifier l’upstream direct derrière edge

curl -sSI http://127.0.0.1:8081/ | head -n 12
curl -sSI http://127.0.0.1:8082/ | head -n 12

Si 8081 et 8082 servent des versions différentes : c’est “normal” en blue/green, mais il faut savoir laquelle est censée être staging/live.

## 3) Diagnostiquer les erreurs Traefik (fichier invalide / middleware manquant)
### 3.1 Grep “level=error”

sudo docker logs edge-traefik --since 5m | grep -Ei 'level=error|middleware|router|service|yaml' | tail -n 80

# Cas typique :

middleware "diag-staging@file" does not exist
→ 21-archicratie-staging.yml référence un middleware absent. Solution : le définir (souvent dans 90-overlay-staging-fix.yml).

## 4) Procédure safe de modification (jamais en aveugle)
### 4.1 Backup

cd /volume2/docker/edge/config/dynamic
TS="$(date +%F-%H%M%S)"
sudo cp -a 90-overlay-staging-fix.yml "90-overlay-staging-fix.yml.bak.$TS"

### 4.2 Édition (ex : ajouter middlewares diag)

Faire une modif minimale

Ne pas casser les règles existantes (Host + PathPrefix)

Respecter les priorités (voir section 5)

### 4.3 Reload Traefik

sudo docker restart edge-traefik

### 4.4 Tests immédiats

curl -sSI -H 'Host: staging.archicratie.trans-hands.synology.me' http://127.0.0.1:18080/ \
 | grep -iE 'HTTP/|location:|x-archi-router'

curl -sSI -H 'Host: staging.archicratie.trans-hands.synology.me' http://127.0.0.1:18080/_auth/whoami \
 | grep -iE 'HTTP/|location:|x-archi-router'

## 5) Priorités Traefik (le point subtil)

Traefik choisit le routeur selon :

la correspondance de règle

la priority (plus grand gagne)

en cas d’égalité, l’ordre interne (à éviter)

### 5.1 Canon pour staging

21-archicratie-staging.yml : priority 10

22-archicratie-authinfo-staging.yml : priority 10000

90-overlay-staging-fix.yml :

fallback host : priority faible (ex: 5) pour ne PAS écraser 21

fallback whoami : priority < 10000 (ex: 9000) pour ne PAS écraser 22

=> On garde 90 comme filet de sécurité / diag, pas comme “source”.

## 6) Rollback (si un changement edge casse staging/live)

cd /volume2/docker/edge/config/dynamic
# choisir le bon backup
sudo mv -f 90-overlay-staging-fix.yml "90-overlay-staging-fix.yml.BAD.$(date +%F-%H%M%S)"
sudo cp -a 90-overlay-staging-fix.yml.bak.YYYY-MM-DD-HHMMSS 90-overlay-staging-fix.yml
sudo docker restart edge-traefik

Puis re-tests section 2.

## 7) Remarques

Les 302 Authelia sont normaux si non authentifié.

Un 404 “Not Found” depuis edge alors que 8081 répond : souvent routeur manquant / invalidé / middleware absent.