Mise en place d'un labo Nginx local avec exemples pratiques

Intro

Cette version française explique Nginx local lab setup with practical examples avec le même objectif pratique que l article source : aider le lecteur à comprendre le contexte, les décisions à prendre et les points à vérifier avant de passer à l action.

Un labo Nginx local vous offre un moyen sûr et rapide d'apprendre, de tester des changements et de dépanner avant de toucher à des environnements partagés. En quelques minutes, vous pouvez déployer une instance Nginx isolée sous votre répertoire personnel, l'exécuter sur des ports non privilégiés et itérer sans risquer la configuration système.

Cette approche est pratique : faites l'inventaire de votre environnement, créez un préfixe Nginx non privilégié, puis implémentez trois petits exemples observables avec curl et les journaux : un site statique, un reverse proxy vers une application locale, et du HTTPS via un certificat auto-signé. Vous verrez les résultats attendus, les écueils fréquents et un plan de retour arrière. À la fin, vous aurez un flux de travail reproductible sur n'importe quel poste.

Versions et inventaire d'environnement

Définissez le périmètre et confirmez vos outils pour un comportement prévisible. Gardez ce pilote simple et mesurable : une machine, des ports non privilégiés et un seul répertoire détenu par l'utilisateur.

Prérequis :

Système d'exploitation : Linux ou macOS. Windows est possible via l'archive officielle Nginx ou WSL ; les commandes ci-dessous supposent un shell Unix.
Outils installés : binaire nginx, curl, openssl, python3.
Ports locaux ouverts : 8080 pour HTTP, 8443 pour HTTPS, 3000 pour un backend local.
Accès en écriture sous votre répertoire personnel.

Confirmez les versions (exemples construits) :

nginx -v
Exemple attendu : nginx version: nginx/1.24.0
curl --version
Exemple attendu : curl 8.4.0
openssl version
Exemple attendu : OpenSSL 3.0.10
python3 --version
Exemple attendu : Python 3.11.x

Notes d'installation (au choix) :

Linux (Debian/Ubuntu) : sudo apt-get update && sudo apt-get install -y nginx curl openssl python3
Linux (RHEL/Fedora) : sudo dnf install -y nginx curl openssl python3
macOS (Homebrew) : brew install nginx curl openssl python

Si Nginx est déjà installé, vous pouvez réutiliser le binaire en pointant vers votre propre préfixe et vos fichiers de configuration pour garder le labo isolé.

Chemin de configuration sûr

Exécutez Nginx avec votre utilisateur, liez des ports élevés et conservez tous les fichiers dans un unique répertoire de labo. Ainsi, vous n'altérez jamais /etc/nginx et n'utilisez pas de privilèges élevés.

Créez l'arborescence du labo :

export LAB="$HOME/nginx-lab"
mkdir -p "$LAB"/{conf, conf/sites, html, logs, certs}

Créez une page index simple :

cat > "$LAB/html/index.html" <<'EOF'
<!doctype html>
<html>
  <head><meta charset="utf-8"><title>Nginx Lab</title></head>
  <body>
    <h1>Nginx Local Lab</h1>
    <p>It works.</p>
  </body>
</html>
EOF

Rédigez la configuration Nginx de base dans $LAB/conf/nginx.conf :

worker_processes  1;
error_log  logs/error.log info;
pid        logs/nginx.pid;

events { worker_connections  1024; }

http {
    include       mime.types;
    default_type  application/octet-stream;

    log_format  main  '$remote_addr - $remote_user [$time_local] "$request" '
                      '$status $body_bytes_sent "$http_referer" '
                      '"$http_user_agent"';

    access_log  logs/access.log  main;

    sendfile        on;
    keepalive_timeout  65;

    include conf/sites/*.conf;
}

Cette configuration utilise $LAB/logs pour les journaux et inclut les sites depuis $LAB/conf/sites. Elle n'effleure jamais /etc/nginx.

Démarrage, arrêt et tests avec votre préfixe :

Test : nginx -p "$LAB" -t -c conf/nginx.conf
Démarrer : nginx -p "$LAB" -c conf/nginx.conf
Recharger après modification : nginx -p "$LAB" -s reload
Arrêter : nginx -p "$LAB" -s stop

Astuce : testez toujours (-t) avant un reload. Nginx refuse de recharger une configuration invalide, un garde-fou utile dans votre labo.

Exemples pratiques

Vous allez implémenter trois scénarios observables : un site statique, un reverse proxy par chemin vers une app locale et du HTTPS sur un port élevé avec un certificat auto-signé.

1) Site statique sur le port 8080

Créez la configuration du site :

# $LAB/conf/sites/static.conf
server {
    listen 8080;
    server_name localhost;

    root   html;
    index  index.html;

    location /healthz {
        return 200 'ok\n';
        add_header Content-Type text/plain;
    }

    location / {
        try_files $uri $uri/ =404;
    }

    error_page 404 /404.html;
    location = /404.html {
        internal;
        return 404 'not found\n';
        add_header Content-Type text/plain;
    }
}

Comportement attendu :

http://127.0.0.1:8080/ sert votre index.html.
http://127.0.0.1:8080/healthz renvoie un simple ok.

2) Reverse proxy de /app/ vers un backend local sur 3000

Démarrez un backend simple (exemple construit) :

python3 -m http.server 3000 --bind 127.0.0.1

Créez la configuration de proxy :

# $LAB/conf/sites/reverse-proxy.conf
server {
    listen 8080;
    server_name localhost;

    # Limitation de débit pour protéger le backend (valeurs d'exemple)
    limit_req_zone $binary_remote_addr zone=api_limit:10m rate=5r/s;

    location /app/ {
        limit_req zone=api_limit burst=10 nodelay;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_http_version 1.1;
        proxy_pass http://127.0.0.1:3000/;
    }
}

Notes :

Le slash final dans location /app/ avec proxy_pass .../ mappe /app/foo vers /foo côté backend, ce qui est généralement souhaité.
limit_req sert ici de garde légère pour simuler des contrôles de production dans le labo.

3) HTTPS sur le port 8443 avec un certificat auto-signé

Générez un certificat auto-signé (sujet d'exemple) :

openssl req -x509 -nodes -days 365 -newkey rsa:2048 \
  -keyout "$LAB/certs/selfsigned.key" \
  -out "$LAB/certs/selfsigned.crt" \
  -subj "/C=US/ST=NA/L=Local/O=Lab/OU=Dev/CN=localhost"

Créez le serveur TLS :

# $LAB/conf/sites/tls.conf
server {
    listen 8443 ssl;
    server_name localhost;

    ssl_certificate     certs/selfsigned.crt;
    ssl_certificate_key certs/selfsigned.key;

    # Paramètres TLS modernes minimaux pour le labo
    ssl_protocols TLSv1.2 TLSv1.3;
    ssl_ciphers HIGH:!aNULL:!MD5;

    root   html;
    index  index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}

Appliquez et testez l'ensemble :

nginx -p "$LAB" -t -c conf/nginx.conf
nginx -p "$LAB" -s reload

À ce stade, vous avez :

Site HTTP statique sur 127.0.0.1:8080
Reverse proxy par chemin sur 127.0.0.1:8080/app/
Site HTTPS statique sur 127.0.0.1:8443

Inventaire du labo (exemple construit) :

Composant	Port	Chemin ou note
Préfixe Nginx	n/a	$HOME/nginx-lab
Site statique HTTP	8080	$LAB/conf/sites/static.conf, $LAB/html
Reverse proxy	8080 (/app/)	$LAB/conf/sites/reverse-proxy.conf -> 127.0.0.1:3000
Site statique HTTPS	8443	$LAB/conf/sites/tls.conf, $LAB/certs
App backend	3000	python3 -m http.server

Vérification et diagnostics

Exécutez des contrôles simples après chaque changement. Toutes les commandes ciblent localhost.

Vérifier le site statique :

curl -i http://127.0.0.1:8080/

Exemple attendu (ligne de statut et quelques en-têtes) :

HTTP/1.1 200 OK
Server: nginx/1.24.0
Content-Type: text/html
Content-Length: <number>

Vérifier l'endpoint santé :

curl -i http://127.0.0.1:8080/healthz

Exemple attendu :

HTTP/1.1 200 OK
Content-Type: text/plain

ok

Vérifier le mapping du reverse proxy :

curl -i http://127.0.0.1:8080/app/

Exemple attendu :

HTTP/1.1 200 OK
Server: nginx/1.24.0

Directory listing for /

Vérifier HTTPS (auto-signé ; utilisez -k pour ignorer la confiance) :

curl -k -i https://127.0.0.1:8443/

Exemple attendu :

HTTP/1.1 200 OK
Server: nginx/1.24.0
Content-Type: text/html

Suivre les journaux pendant les tests :

tail -f "$LAB/logs/access.log" "$LAB/logs/error.log"

Confirmer les sockets à l'écoute :

Linux : ss -lntp | grep -E ':8080|:8443'
macOS : lsof -iTCP -sTCP:LISTEN -n | egrep ':8080|:8443'

La sortie attendue montre nginx à l'écoute sur 127.0.0.1:8080 et 0.0.0.0:8443 (ou équivalent, selon votre config).

Valider la syntaxe avant tout rechargement :

nginx -p "$LAB" -t -c conf/nginx.conf

Exemple attendu :

nginx: the configuration file conf/nginx.conf syntax is ok
nginx: configuration file conf/nginx.conf test is successful

En cas d'échec, cherchez l'erreur précise dans $LAB/logs/error.log, puis relancez -t pour repérer tôt les erreurs de syntaxe.

Pannes courantes et reprise

Anticipez les problèmes et restez prêt à revenir en arrière en versionnant ou copiant les fichiers stables.

Modèle de rollback rapide (étapes construites) :

Conservez une copie de la dernière config connue : cp -a "$LAB/conf" "$LAB/conf.good.$(date +%s)"
En cas d'échec de reload, restaurez : rsync -a --delete "$LAB/conf.good.TIMESTAMP/" "$LAB/conf/" && nginx -p "$LAB" -t -c conf/nginx.conf && nginx -p "$LAB" -s reload

Problèmes fréquents et correctifs :

Symptôme	Cause probable	Correctif rapide
nginx -t échoue avec ligne: col	Erreur de syntaxe (point-virgule manquant, directive invalide)	Ouvrez le fichier indiqué par nginx -t, corrigez la ligne, retestez
curl vers :8080 retourne connection refused	Nginx non démarré ou écoute sur une autre IP	Vérifiez ss/lsof, démarrez avec nginx -p "$LAB" -c conf/nginx.conf
curl vers :8080/app/ renvoie 404	Décalage de chemin proxy	Assurez location /app/ et proxy_pass http://127.0.0.1:3000/ (notez le slash final)
502 Bad Gateway sur /app/	Backend non lancé	Lancez python3 -m http.server 3000 et réessayez
403 Forbidden sur fichiers statiques	Mauvais root ou permissions	root html; vérifiez l'existence et la lisibilité par votre utilisateur
Alerte TLS ou handshake	Certificat auto-signé non approuvé	Utilisez curl -k pour tester ; dans un navigateur, importez ou poursuivez uniquement pour le labo
Port déjà utilisé	Un autre processus occupe 8080/8443	Changez les ports listen ou stoppez l'autre processus

En cas de doute, augmentez temporairement la verbosité :

# Dans nginx.conf (bloc http), temporairement :
error_log logs/error.log debug;

Reproduisez la requête en échec, inspectez error.log, puis revenez au niveau normal pour éviter le bruit.

Checklist d'exploitation

Procédure courte et répétable pour déployer et valider votre labo Nginx local. Tous les chemins sont sous $HOME/nginx-lab.

Setup

Assurez-vous que nginx, curl, openssl, python3 sont installés et dans le PATH.
mkdir -p $LAB/{conf, conf/sites, html, logs, certs}
Créez $LAB/conf/nginx.conf comme ci-dessus.
Créez $LAB/conf/sites/static.conf et reverse-proxy.conf comme ci-dessus.
Écrivez index.html dans $LAB/html.
Générez les certificats auto-signés dans $LAB/certs.

Start

Lancez le backend : python3 -m http.server 3000 --bind 127.0.0.1
nginx -p "$LAB" -t -c conf/nginx.conf
nginx -p "$LAB" -c conf/nginx.conf

Verify

curl -i http://127.0.0.1:8080/
curl -i http://127.0.0.1:8080/healthz
curl -i http://127.0.0.1:8080/app/
curl -k -i https://127.0.0.1:8443/
tail -f $LAB/logs/access.log $LAB/logs/error.log (si nécessaire)

Iterate safely

Modifiez un fichier de site sous conf/sites.
nginx -p "$LAB" -t -c conf/nginx.conf
nginx -p "$LAB" -s reload
Rejouez les contrôles curl ciblés.

Stop and clean up

nginx -p "$LAB" -s stop
pkill -f "python3 -m http.server 3000" (ou Ctrl+C dans son terminal)

Extensions optionnelles (plus tard) :

Ajoutez gzip et des en-têtes de cache au contenu statique.
Introduisez un second upstream et testez proxy_next_upstream et des health checks.
Créez un bloc serveur séparé pour une API sur un port distinct, puis testez CORS.

Gardez chaque extension petite et vérifiable.

Conclusion

Vous disposez maintenant d'un labo Nginx sûr et non privilégié qui sert du contenu statique, proxifie vers un backend local et termine TLS avec un certificat auto-signé. La structure regroupe tous les fichiers sous un seul préfixe, utilise des ports non privilégiés et s'appuie sur nginx -t ainsi que sur les journaux d'accès et d'erreur pour un feedback rapide.

Pour la suite, étendez une capacité à la fois : ajoutez des en-têtes de cache, expérimentez la limitation de débit ou entraînez-vous à des bascules blue/green en gardant deux fichiers de site et en alternant les includes. Gardez des changements petits, validez avec curl et privilégiez reload à restart. Votre apprentissage restera reproductible, observable et à faible risque.

Intro

Versions et inventaire d'environnement

Chemin de configuration sûr

Exemples pratiques

1) Site statique sur le port 8080

2) Reverse proxy de /app/ vers un backend local sur 3000

3) HTTPS sur le port 8443 avec un certificat auto-signé

Vérification et diagnostics

Pannes courantes et reprise

Checklist d'exploitation

Conclusion

Score de qualité de l’article