Back to Blog
January 15, 20261,000 views

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)

# Upstream blocks: define your app servers
upstream frontend {
    server frontend_container:3000;
    keepalive 16;  # reuse connections (huge perf win)
}

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;

    # API routes -> Django
    location /api/ {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";  # required for 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;
    }

    # Static files -> Django (with caching)
    location /static/ {
        proxy_pass http://backend;
        expires 30d;
        add_header Cache-Control "public, immutable";
    }

    # Everything else -> 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 for 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.

# Redirect HTTP -> HTTPS
server {
    listen 80;
    server_name yourapp.com www.yourapp.com;
    return 301 https://yourapp.com$request_uri;
}

# Redirect www -> non-www
server {
    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;
}

# Main site (canonical)
server {
    listen 443 ssl;
    server_name yourapp.com;
    # ... your config
}

Les 5 principes fondamentaux à connaître

DirectiveFonctionnalitésPourquoi c'est important
proxy_http_version 1.1Utilise HTTP/1.1 pour les connexions en amontNé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 clientRequis pour la diffusion SSR, SSE, en temps réel
client_max_body_size 20 MoTaille maximale des fichiers à téléchargerLa valeur par défaut est de 1 Mo : le téléchargement des fichiers échouera
proxy_set_header X-Forwarded-Proto $schemeIndique au serveur si la requête a été effectuée via HTTPSDjango 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.

# Quick debugging commands
nginx -t                    # test config syntax
nginx -s reload             # reload without downtime
tail -f /var/log/nginx/error.log   # watch errors live
curl -I https://yourapp.com  # check response headers

Nginx, 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