Publish an application with Nginx: proxy_pass, headers and certificates

To publish an application with Nginx, you declare a server that listens under the public name, a location that sends requests to the application with proxy_pass, and four headers that tell the application who is really calling it. Without these headers, the application believes everything comes from 127.0.0.1 over HTTP. This lesson is the optional Nginx module of the training: it takes up the publication gestures already seen with Traefik, in Nginx syntax.

What you will learn

The lesson follows the order of a publication: route, forward, spread, then secure with a certificate.

• Publish an application under a name with proxy_pass.
• Preserve the path and the host of the original request.
• Forward the X-Forwarded-* headers the application expects.
• Declare an upstream and understand its passive probes.
• Obtain a certificate with Nginx's ACME module (in preview) or with certbot.

Prerequisites

This lesson assumes you understand the path of a request and have already seen an Nginx configuration file.

• The path from the DNS name to the backend, SNI and the Host header: Publish a web service.
• Automatic certificates and ACME: Automatic certificates.
• Nginx installation and basics: Nginx: practical guide (in French).

How does Nginx route a request to an application?

Nginx first chooses the server block from the requested name, then the location block from the path, and proxy_pass sends the request to the backend. It is the same split as Traefik's router, with one difference: everything is written in configuration files that you test then reload, with no automatic discovery of containers.

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

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

This file publishes the application listening on port 8080 of the machine under the name app.lab.test. The server_name serves to choose the right block when several names share the same address, and location / catches all paths.

The trailing slash of proxy_pass

With proxy_pass http://127.0.0.1:8080; the requested path is forwarded as is. With proxy_pass http://127.0.0.1:8080/; (a slash, hence a URI), Nginx replaces the part of the path that matches the location with that URI. The two writings are not equivalent: test with curl the path that actually reaches the backend.

Which headers should you forward to the application?

Forward the original host, the client's address, the chain of relays and the protocol used. By default, Nginx rewrites Host with the name and port of the backend and says nothing about the real client. The application can then neither generate the right absolute addresses, nor log the right origin, nor know that the client arrived over 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;
}

The $proxy_add_x_forwarded_for variable appends the client's address to the chain already received instead of overwriting it: this is what preserves the trace when another relay sits upstream. Keep in mind that a client can send an X-Forwarded-For header itself: the application must only trust it behind a proxy it knows.

How do you spread the load with upstream?

An upstream block names a group of servers, and proxy_pass designates it by its name. The default distribution goes round the servers of the group in turn. With open source Nginx, failure detection is passive: a server is set aside when requests fail, according to max_fails and fail_timeout, but Nginx does not send a probe request on its own.

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;
}

This difference matters in operations: with Traefik, an active probe removes a backend before a user meets it; with open source Nginx, it is the first failing requests that trigger the removal. Active probes (health_check) belong to Nginx's commercial offer.

How do you obtain a certificate?

Two paths exist: Nginx's ACME module (in preview), which renews by itself, or the external tool certbot, which modifies the configuration and schedules renewal. In both cases, the principle is that of the lesson on automatic certificates: prove to the authority that you control the name, then retrieve a certificate renewed before it expires.

The ngx_http_acme_module module is configured in Nginx itself: an acme_issuer block describes the authority (ACME directory address, contact, state_path where the account key and the certificates are kept), an acme_shared_zone shares the state between processes, and the HTTPS server declares acme_certificate then reads the certificate in $acme_certificate and $acme_certificate_key. A server on port 80 must remain reachable for the HTTP-01 challenge. The module also accepts the tls-alpn-01 challenge.

Module or certbot

The ACME module saves one more tool and keeps the state in Nginx, but it is in preview: its versions are 0.x, it handles neither DNS-01 nor wildcards, and its interface may still change. This is not a stable status. It is loaded as a dynamic module or compiled with Nginx. certbot is more widespread, simple to install from a package and well documented. Choose according to what your team already knows how to operate, weighing this status for a production, and check in both cases that renewal is observed, not assumed.

How do you validate before reloading?

Always test the configuration with nginx -t before reloading it, then check the real response with curl. Reloading an invalid configuration is refused and keeps the old one, but only a test request proves that the path, the host and the headers arrive as planned at the backend.

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

If the response is not the expected one, read Nginx's error log: a 502 indicates an unreachable backend, a 504 a backend that is too slow, and a 404 a server or location block that does not match the name or the path.

Practice: publish an application with Nginx

The lab starts from a small application running on the machine, with an Nginx container and its starting configuration. It asks you to configure Nginx as a reverse proxy of app.lab.test to the local application, to preserve the path and the host of the request and to forward the headers expected from an application behind a proxy.

Guided lab Practice

Learn how to do it

Publish an application with Nginx

$ dsoxlab run pub-nginx-publication

Environment: VM·Duration: ~30 min

How it is checked: the state of the system is checked after a reboot, not the command you typed.

First time? What DSOXLab is and how to install it

DSOXLab is the command line that prepares a disposable environment (an isolated shell or a VM), runs the lab scenario, then checks the real state of the system and computes a score. Nothing is installed or broken on your workstation.

It needs Python 3.11 or later, uv or pipx, and git. The installation guide details these prerequisites; on Windows, or on a Mac without Python, use the appliance instead.

This lab starts virtual machines: it also needs ansible-playbook, a hypervisor (KVM or Incus), Terraform and hardware virtualization (/dev/kvm), which inside a VirtualBox VM means nested virtualization. The first time, dsoxlab start pub-nginx-publication checks all of it before creating the machines. Prepare your machine for vm labs.

Install the CLI and add the catalogue, once:

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

Before you run the lab, check:

• DSOXLab installed
• catalogue available
• compatible environment (isolated shell or VM)

To check, nothing is probed from this page: run dsoxlab doctor. Read the diagnosis

Run this lab, then validate your work:

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

See every lab: dsoxlab list-labs. Track your progress: dsoxlab progress. The full dsoxlab guide covers scoring and the pitfalls.

Key points

Nginx publishes an application with a server, a location and proxy_pass.

• server_name chooses the block, location chooses the path.
• Forward Host, X-Real-IP, X-Forwarded-For and X-Forwarded-Proto.
• An open source upstream detects failures passively.
• The ACME module (in preview, so not a stable status) or certbot renew certificates.
• nginx -t validates, curl proves.

Knowledge check

Knowledge check

Check what you have learned with this interactive quiz

8 questions

8 min

70% to pass

How it works

• The timer starts when you click Start
• Multiple choice, true/false and short answer questions
• You can move between questions
• Detailed results are shown at the end

Start the quiz

Starts the quiz and the timer

×

See in the glossary →