Documentation règle transversale résolution DNS dynamique dans proxies Nginx (anti-502)

common/nginx-proxy-dns-resolution.md

@@ -0,0 +1,80 @@
+# Règle d'Or : Résolution DNS Dynamique dans les Proxies Nginx Docker
+
+## 1. Contexte du Problème (Cause Racine de l'Erreur 502)
+
+Dans un environnement Docker où les conteneurs sont reliés par un réseau virtuel ( ou réseau nommé partagé comme `n8n`), chaque conteneur peut obtenir une nouvelle adresse IP interne (ex. `172.27.0.x`) à chaque redémarrage, mise à jour ou recréation.
+
+Par défaut dans Nginx, lorsqu'une directive `proxy_pass` utilise un nom d'hôte statique direct :
+```nginx
+# ❌ CONFIGURATION VULNÉRABLE (Résolution DNS statique au boot)
+location / {
+    proxy_pass http://mon-backend:8080;
+}
+```
+Nginx résout le nom `mon-backend` **une seule fois au démarrage de Nginx** et met l'adresse IP en cache de manière permanente en mémoire.
+
+### Conséquence :
+Dès que `mon-backend` redémarre ou est mis à jour :
+1. `mon-backend` reçoit une nouvelle adresse IP Docker (ex. `172.27.0.43`).
+2. Nginx continue d'envoyer les requêtes vers l'ancienne IP (ex. `172.27.0.37`).
+3. Nginx reçoit un `Connection refused` ou `No route to host` et renvoie un **502 Bad Gateway**.
+4. Le service reste en panne jusqu'à un redémarrage manuel du conteneur Nginx.
+
+---
+
+## 2. Le Pattern Requis : `resolver 127.0.0.11` + Variable Dynamique
+
+Pour forcer Nginx à réévaluer la résolution DNS selon le TTL Docker sans dépendre d'un cache figé, **deux éléments sont indispensables** :
+
+1. La déclaration explicite du DNS interne Docker (`127.0.0.11`) avec un TTL court (ex. `valid=10s`).
+2. L'assignation de l'URL cible dans une **variable intermédiaire** (`set $upstream_var ...`). Nginx est conçu pour ne pas pré-résoudre les variables au boot, mais au moment du traitement de la requête.
+
+### Configuration Standard Recommandée :
+
+```nginx
+server {
+    listen 80;
+    server_name service.bolbol.tn;
+
+    # 1. DNS interne Docker (127.0.0.11) avec re-résolution toutes les 10s
+    resolver 127.0.0.11 valid=10s ipv6=off;
+
+    # 2. Définition dynamique de l'amont via variable
+    location / {
+        set $backend_upstream http://mon-service:8080;
+        proxy_pass $backend_upstream;
+
+        proxy_http_version 1.1;
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection $connection_upgrade;
+        proxy_buffering off;
+        proxy_read_timeout 3600s;
+        proxy_send_timeout 3600s;
+        chunked_transfer_encoding on;
+    }
+}
+```
+
+---
+
+## 3. Périmètre Appliqué sur le NAS (21/08/2026)
+
+| Service Proxy | Fichier de Configuration | Statut |
+|---------------|--------------------------|--------|
+| `baserow-oauth-proxy` | `/volume1/docker/baserow-oauth-stub/nginx.conf` | ✅ Corrigé & Testé en direct |
+| `baserow-schema-mcp-proxy` | `/volume1/docker/baserow-schema-mcp/nginx.conf` | ✅ Corrigé & Validé |
+| `redaction-pro` | `/volume1/docker/redaction-pro/nginx.conf` | ✅ Corrigé & Validé |
+| `formation-consultant` | `/volume1/docker/formation-consultant/nginx.conf` | N/A (fichiers statiques locaux, aucun upstream) |
+
+---
+
+## 4. Protocole de Test de Résilience Obligatoire
+
+Lors de la mise en place ou modification d'un reverse proxy Nginx :
+1. Valider la syntaxe : `docker exec <proxy> nginx -t`
+2. Recharger la config : `docker exec <proxy> nginx -s reload`
+3. **Test d'attribution dynamique** : Redémarrer le conteneur backend (`docker restart <backend>`) et vérifier avec `curl` l'accès via le proxy **sans toucher au conteneur proxy**.