Publier une application avec Nginx : proxy_pass, en-têtes transmis et certificats

Pour publier une application avec Nginx, on déclare un server qui écoute sous le nom public, un location qui envoie les requêtes vers l'application avec proxy_pass, et quatre en-têtes qui disent à l'application qui l'appelle vraiment. Sans ces en-têtes, l'application croit que tout vient de 127.0.0.1 en HTTP. Cette leçon est le module facultatif Nginx de la formation : elle reprend les gestes de publication déjà vus avec Traefik, dans la syntaxe de Nginx.

Ce que vous allez apprendre

La leçon suit l'ordre d'une publication : router, transmettre, répartir, puis sécuriser par un certificat.

• Publier une application sous un nom avec proxy_pass.
• Préserver le chemin et l'hôte de la requête d'origine.
• Transmettre les en-têtes X-Forwarded-* attendus par l'application.
• Déclarer un upstream et comprendre ses sondes passives.
• Obtenir un certificat par le module ACME de Nginx (en preview) ou par certbot.

Prérequis

Cette leçon suppose que vous comprenez le trajet d'une requête et que vous avez déjà vu un fichier de configuration Nginx.

• Le trajet du nom DNS jusqu'au backend, le SNI et l'en-tête Host : Publier un service web.
• Les certificats automatiques et ACME : Certificats automatiques.
• L'installation et les bases de Nginx : Nginx : guide pratique.

Comment Nginx route-t-il une requête vers une application ?

Nginx choisit d'abord le bloc server à partir du nom demandé, puis le bloc location à partir du chemin, et proxy_pass envoie la requête au backend. C'est le même découpage que le routeur de Traefik, avec une différence : tout est écrit dans des fichiers de configuration que vous testez puis rechargez, sans découverte automatique de conteneurs.

server {
    listen 80;
    server_name app.lab.test;

    location / {
        proxy_pass http://127.0.0.1:8080;
    }
}

Ce fichier publie l'application qui écoute sur le port 8080 de la machine sous le nom app.lab.test. Le server_name sert à choisir le bon bloc quand plusieurs noms partagent la même adresse, et location / attrape tous les chemins.

Le slash final de proxy_pass

Avec proxy_pass http://127.0.0.1:8080; le chemin demandé est transmis tel quel. Avec proxy_pass http://127.0.0.1:8080/; (un slash, donc un URI), Nginx remplace la partie du chemin qui correspond au location par cet URI. Les deux écritures ne sont pas équivalentes : testez avec curl le chemin qui arrive réellement au backend.

Quels en-têtes transmettre à l'application ?

Transmettez l'hôte d'origine, l'adresse du client, la chaîne des relais et le protocole utilisé. Par défaut, Nginx réécrit Host avec le nom et le port du backend et ne dit rien du client réel. L'application ne peut alors ni générer les bonnes adresses absolues, ni journaliser la bonne origine, ni savoir que le client est arrivé en HTTPS.

location / {
    proxy_pass http://127.0.0.1:8080;
    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;
}

La variable $proxy_add_x_forwarded_for ajoute l'adresse du client à la chaîne déjà reçue au lieu de l'écraser : c'est ce qui préserve la trace quand un autre relais se trouve en amont. Gardez en tête qu'un client peut envoyer lui-même un en-tête X-Forwarded-For : l'application ne doit lui faire confiance que derrière un proxy qu'elle connaît.

Comment répartir la charge avec upstream ?

Un bloc upstream nomme un groupe de serveurs, et proxy_pass le désigne par son nom. La répartition par défaut tourne tour à tour sur les serveurs du groupe. Avec Nginx open source, la détection d'une panne est passive : un serveur est écarté quand des requêtes échouent, selon max_fails et fail_timeout, mais Nginx n'envoie pas de requête de sonde de lui-même.

upstream app_backend {
    server 127.0.0.1:8080 max_fails=2 fail_timeout=10s;
    server 127.0.0.1:8081 max_fails=2 fail_timeout=10s;
}

Cette différence compte à l'exploitation : avec Traefik, une sonde active retire un backend avant qu'un utilisateur ne le rencontre ; avec Nginx open source, ce sont les premières requêtes en échec qui déclenchent le retrait. Les sondes actives (health_check) relèvent de l'offre commerciale de Nginx.

Comment obtenir un certificat ?

Deux chemins existent : le module ACME de Nginx (en preview), qui renouvelle de lui-même, ou l'outil externe certbot, qui modifie la configuration et planifie le renouvellement. Dans les deux cas, le principe est celui de la leçon sur les certificats automatiques : prouver à l'autorité que vous contrôlez le nom, puis récupérer un certificat renouvelé avant son expiration.

Le module ngx_http_acme_module se configure dans Nginx lui-même : un bloc acme_issuer décrit l'autorité (adresse du répertoire ACME, contact, state_path où sont conservées la clé du compte et les certificats), un acme_shared_zone partage l'état entre les processus, et le server en HTTPS déclare acme_certificate puis lit le certificat dans $acme_certificate et $acme_certificate_key. Un server sur le port 80 doit rester joignable pour le défi HTTP-01. Le module accepte aussi le défi tls-alpn-01.

Module ou certbot

Le module ACME évite un outil de plus et garde l'état dans Nginx, mais il est en preview (aperçu) : ses versions sont en 0.x, il ne gère ni DNS-01 ni les jokers, et son interface peut encore changer. Ce n'est pas un statut stable. Il se charge comme un module dynamique ou se compile avec Nginx. certbot est plus répandu, simple à installer par paquet et bien documenté. Choisissez selon ce que votre équipe sait déjà exploiter, en pesant ce statut pour une production, et vérifiez dans les deux cas que le renouvellement est observé, pas supposé.

Comment valider avant de recharger ?

Testez toujours la configuration avec nginx -t avant de la recharger, puis vérifiez la réponse réelle avec curl. Un rechargement d'une configuration invalide est refusé et garde l'ancienne, mais seule une requête de test prouve que le chemin, l'hôte et les en-têtes arrivent comme prévu au backend.

nginx -t
curl -sS -H 'Host: app.lab.test' http://127.0.0.1/

Si la réponse n'est pas celle attendue, lisez le journal d'erreurs de Nginx : un 502 indique un backend injoignable, un 504 un backend trop lent, et un 404 un bloc server ou location qui ne correspond pas au nom ou au chemin.

Mettre en pratique : publier une application avec Nginx

Le lab part d'une petite application qui tourne sur la machine, avec un conteneur Nginx et sa configuration de départ. Il vous demande de configurer Nginx comme reverse proxy de app.lab.test vers l'application locale, de préserver le chemin et l'hôte de la requête et de transmettre les en-têtes attendus d'une application derrière un proxy.

Lab guidé Pratique

Apprendre à faire

Publier une application avec Nginx

$ dsoxlab run pub-nginx-publication

Environnement : VM·Durée : ~30 min

Vérification : l'état du système est vérifié après reboot, pas la commande tapée.

Première fois ? Qu'est-ce que DSOXLab et comment l'installer

DSOXLab est la ligne de commande qui prépare un environnement jetable (un shell isolé ou une VM), déroule le scénario du lab, puis vérifie l'état réel du système et calcule un score. Rien n'est installé ni cassé sur votre poste de travail.

Il faut Python 3.11 ou plus récent, uv ou pipx, et git. Le guide d'installation détaille ces prérequis ; sous Windows, ou sur un Mac sans Python, passez plutôt par l'appliance.

Ce lab démarre des machines virtuelles : il demande en plus ansible-playbook, un hyperviseur (KVM ou Incus), Terraform et la virtualisation matérielle (/dev/kvm), c'est-à-dire, dans une VM VirtualBox, la virtualisation imbriquée. La première fois, dsoxlab start pub-nginx-publication vérifie tout cela avant de créer les machines. Préparer le poste pour les labs vm.

Installer la CLI et brancher le catalogue, une seule fois :

uv tool install dsoxlab   # ou : pipx install dsoxlab
dsoxlab catalog add https://github.com/stephrobert/publier-service-dsoxlab-training

Avant de lancer le lab, vérifiez :

• DSOXLab installé
• catalogue disponible
• environnement compatible (shell isolé ou VM)

Pour le vérifier, rien n'est sondé depuis cette page : lancez dsoxlab doctor. Lire le diagnostic

Lancer ce lab, puis valider votre travail :

dsoxlab run pub-nginx-publication
dsoxlab check pub-nginx-publication

Voir tous les labs : dsoxlab list-labs. Suivre sa progression : dsoxlab progress. Le guide complet de dsoxlab détaille le calcul du score et les pièges.

À retenir

Nginx publie une application par un server, un location et proxy_pass.

• server_name choisit le bloc, location choisit le chemin.
• Transmettez Host, X-Real-IP, X-Forwarded-For et X-Forwarded-Proto.
• Un upstream open source détecte les pannes de façon passive.
• Le module ACME (en preview, donc pas un statut stable) ou certbot renouvellent les certificats.
• nginx -t valide, curl prouve.

Contrôle de connaissances

Contrôle de connaissances

Validez vos connaissances avec ce quiz interactif

8 questions

8 min.

70% requis

Informations

• Le chronomètre démarre au clic sur Démarrer
• Questions à choix multiples, vrai/faux et réponses courtes
• Vous pouvez naviguer entre les questions
• Les résultats détaillés sont affichés à la fin

Démarrer le quiz

Lance le quiz et démarre le chronomètre

×

📖 Voir la documentation →