NeahNew/CAPROVER_NGINX_FIX.md

Fix Nginx CapRover - Erreur "upstream sent too big header"

🔍 Problème

Erreur 502 avec message Nginx :

upstream sent too big header while reading response header from upstream

Cause : Le cookie de session NextAuth (JWT avec tokens Keycloak) dépasse 4KB, la limite par défaut de Nginx.

✅ Solution : Modifier la configuration CapRover

Option 1 : Via CapRover Dashboard (RECOMMANDÉ)

1. Aller dans CapRover Dashboard
2. Sélectionner votre app (hub.slm-lab.net)
3. Aller dans "HTTP Settings"
4. Cliquer sur "Edit Nginx Configuration" (si disponible)
5. OU aller dans "App Configs" → "nginx"

Option 2 : Modifier le template Nginx directement

Si vous avez accès au serveur CapRover, modifier le template dans :

• /captain/templates/nginx.conf (template principal)
• OU créer un override dans votre app

📝 Configuration à Ajouter

Dans le bloc location /, ajouter ces directives AVANT proxy_pass :

location / {
    # ============================================
    # FIX: Augmenter la limite des headers pour NextAuth
    # ============================================
    proxy_buffer_size 16k;
    proxy_buffers 8 16k;
    proxy_busy_buffers_size 32k;
    large_client_header_buffers 4 32k;
    
    # Timeouts (pour éviter les timeouts)
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
    
    # Configuration proxy existante
    proxy_pass $upstream;
    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;
    
    # WebSocket support (si activé)
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_http_version 1.1;
}

🔧 Configuration Complète Modifiée

Voici le bloc location / complet avec les corrections :

location / {
    # FIX: Headers trop grands pour NextAuth
    proxy_buffer_size 16k;
    proxy_buffers 8 16k;
    proxy_busy_buffers_size 32k;
    large_client_header_buffers 4 32k;
    
    # Timeouts
    proxy_connect_timeout 60s;
    proxy_send_timeout 60s;
    proxy_read_timeout 60s;
    
    # Proxy configuration
    proxy_pass $upstream;
    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;
    
    # WebSocket (si activé)
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_http_version 1.1;
}

🎯 Méthode via CapRover Dashboard

Si CapRover permet l'édition Nginx :

1. Dashboard CapRover → Votre app
2. "App Configs" → "nginx"
3. Ajouter dans "Custom Nginx Configuration" :

location / {
    proxy_buffer_size 16k;
    proxy_buffers 8 16k;
    proxy_busy_buffers_size 32k;
    large_client_header_buffers 4 32k;
}

4. Sauvegarder → CapRover regénère la config

Si CapRover ne permet pas l'édition :

Option A : Modifier le template CapRover (avancé)

• Accéder au serveur CapRover
• Modifier /captain/templates/nginx.conf
• Redémarrer CapRover

Option B : Créer un fichier de configuration personnalisé

• Créer un fichier dans votre app
• L'inclure dans la config Nginx

🔄 Après Modification

1. Vérifier la config Nginx :

sudo nginx -t

2. Recharger Nginx :

sudo systemctl reload nginx
# OU si CapRover gère Nginx
docker exec captain-nginx nginx -s reload

3. Tester la connexion :

• Se connecter via Keycloak
• Vérifier que l'erreur 502 ne se produit plus

📊 Explication

Avant :

• Limite par défaut Nginx : 4KB pour les headers
• Cookie NextAuth : ~4-7KB (JWT avec tokens Keycloak)
• Résultat : ❌ Erreur 502

Après :

• Limite augmentée : 32KB pour les headers
• Cookie NextAuth : ~4-7KB
• Résultat : ✅ Fonctionne

⚠️ Note Importante

Si vous modifiez le template CapRover directement, vos modifications seront écrasées lors d'une mise à jour de CapRover.

Recommandation : Utiliser la méthode "Custom Nginx Configuration" dans CapRover si disponible, ou documenter vos modifications pour les réappliquer après mise à jour.

---

Document créé le : $(date) Priorité : HAUTE - Résout l'erreur 502