Nginx pour les développeurs : le guide de configuration que vous allez vraiment ajouter à vos favoris
Les fichiers de configuration Nginx ressemblent à du charabia tant qu'on n'en a pas saisi le principe. Ce guide explique le rôle de chaque directive et propose des configurations prêtes à copier-coller pour les cinq configurations les plus courantes.
Le modèle mental : Nginx, c'est comme un service du courrier
Imaginez Nginx comme un service du courrier. Les requêtes arrivent à l'accueil (port 80/443). Le service du courrier vérifie l'étiquette d'adresse (server_name) pour acheminer la requête vers le bon service (server block). Au sein du service, il vérifie l'objet (location) pour acheminer la requête vers la bonne personne (upstream/file).
C'est tout. Dans Nginx, tout se résume à : détecter une requête → effectuer une action en conséquence.
Configuration 1 : Next.js + Django derrière Nginx (la plus courante)
# Blocs « upstream » : définissez vos serveurs
d'applicationupstream frontend {
server frontend_container:3000;
keepalive 16; # réutilisation des connexions (gain de performances considérable)
}
upstream backend {
server backend_container:8000;
keepalive 8;
}
server {
listen 443 ssl;
server_name yourapp.com;
# SSL (Let's Encrypt)
ssl_certificate /etc/letsencrypt/live/yourapp.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/yourapp.com/privkey.pem;
# Routes API -> Django
location /api/ {
proxy_pass http://backend;
proxy_http_version 1.1;
proxy_set_header Connection ""; # requis pour keepalive
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-Proto $scheme;
}
# Admin -> Django
location /admin/ {
proxy_pass http://backend;
proxy_set_header Host $host;
}
# Fichiers statiques -> Django (avec mise en cache)
location /static/ {
proxy_pass http://backend;
expires 30d;
add_header Cache-Control "public, immutable";
}
# Tout le reste -> Next.js
location / {
proxy_pass http://frontend;
proxy_http_version 1.1;
proxy_set_header Connection "";
proxy_set_header Host $host;
proxy_buffering off; # important pour le streaming SSR
}
}Configuration 2 : Redirection HTTPS + URL canonique « www »
Il y a deux choses indispensables pour tout site de production : imposer le protocole HTTPS et choisir un domaine canonique (avec ou sans « www »). Sans cela, Google considère qu'il s'agit de deux sites distincts, ce qui nuit à votre référencement.
# Redirection HTTP vers HTTPSserver
{
listen 80;
server_name yourapp.com www.yourapp.com;
return 301 https://yourapp.com$request_uri;
}
# Redirection www vers
non-wwwserver {
listen 443 ssl;
server_name www.yourapp.com;
ssl_certificate /etc/letsencrypt/live/yourapp.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/yourapp.com/privkey.pem;
return 301 https://yourapp.com$request_uri;
}
# Site principal (canonique)
server {
listen 443 ssl;
server_name yourapp.com;
# ... votre configuration
}Les 5 principes fondamentaux à connaître
| Directive | Fonctionnalités | Pourquoi c'est important |
|---|---|---|
| proxy_http_version 1.1 | Utilise HTTP/1.1 pour les connexions en amont | Nécessaire au bon fonctionnement du keepalive |
| proxy_set_header Connection "" | Efface l'en-tête « Connection » | Sans cela, la fonction keepalive est désactivée |
| proxy_buffering désactivé | Transmet la réponse directement au client | Requis pour la diffusion SSR, SSE, en temps réel |
| client_max_body_size 20 Mo | Taille maximale des fichiers à télécharger | La valeur par défaut est de 1 Mo : le téléchargement des fichiers échouera |
| proxy_set_header X-Forwarded-Proto $scheme | Indique au serveur si la requête a été effectuée via HTTPS | Django en a besoin pour la protection contre les attaques CSRF et les redirections |
Débogage : quand les choses tournent mal
502 Bad Gateway : Nginx ne parvient pas à se connecter à votre serveur en amont. Le conteneur de votre application n'est pas en cours d'exécution ou se trouve sur un autre réseau Docker.
504 Délai d'attente de la passerelle : votre application est trop lente. Augmentez la valeur de `proxy_read_timeout` ou optimisez votre application.
413 Entité de requête trop volumineuse : le fichier téléchargé dépasse la valeur de `client_max_body_size`. Augmentez cette valeur.
Boucle de redirection 301 : votre application effectue une redirection vers HTTPS, mais l'en-tête X-Forwarded-Proto n'est pas défini, ce qui lui fait croire qu'il s'agit toujours d'une connexion HTTP.
# Commandes de débogage
rapide nginx -t # Vérifier la syntaxe
de la configuration nginx -s reload # Recharger sans interruption de service
tail -f /var/log/nginx/error.log # Afficher les erreurs en temps
réel curl -I https://yourapp.com # Vérifier les en-têtes de réponseNginx, c'est le videur de votre boîte de nuit. C'est lui qui décide qui entre, où les clients vont et à quelle vitesse. Prenez 30 minutes pour le comprendre et vous gagnerez 30 heures de débogage en production.
— alokknight Ingénierie
