# 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**.