Lesson 9 of 14 · 10 min · HTTP, TLS and traffic management

Reverse proxies with nginx

Covers: nginx 1.24 on Ubuntu 24.04, Python http.server backends. Updated 13 Nov 2026. Part of the DevOps Engineer roadmap.

What you will learn

  • Forward proxy versus reverse proxy
  • What a reverse proxy does for you: TLS, routing, caching, protection, compression
  • A working nginx config with proxy_pass and the headers to forward
  • Why the backend sees the proxy's address, and how to recover the client's
  • Timeouts, WebSockets, and debugging 502/504

In simple words

A reverse proxy is the receptionist of a website. Every visitor speaks to the receptionist first, who then passes each request to the right room behind. Visitors never see the rooms themselves. This lesson sets one up with nginx and explains the errors you will meet.

Words to know

  • Proxy: a go-between that passes requests on for someone else.
  • Reverse proxy: a server that stands in front of your applications and forwards requests to them.
  • Backend: the application server behind the proxy that does the real work.
  • 502 / 504: errors from the proxy: the backend gave a bad answer (502) or took too long (504).

Forward and reverse

  • A forward proxy sits in front of clients and makes requests on their behalf (a corporate proxy that filters what employees reach).
  • A reverse proxy sits in front of servers. Clients think they talk to the site; the proxy receives the request and passes it to one of the real backends, then returns the answer. nginx, HAProxy, Envoy, Traefik, Caddy, Apache and cloud load balancers all work this way.
 browser ──HTTPS──▶ reverse proxy ──HTTP──▶ app server 1
                    (nginx, :443)     └────▶ app server 2

Why put one in front

  • TLS termination: certificates live in one place; apps speak plain HTTP on the private network.
  • Routing: /api/ to the API service, / to the web front end, by host name or path, one public IP for many services.
  • Load balancing and failover across several backends (next lesson).
  • Serving static files and compression fast, so the app does not.
  • Caching of responses, and buffering slow clients so app workers are not tied up.
  • Protection: rate limiting, request size limits, hiding internal addresses, blocking bad requests, an IP allow-list.
  • Zero-downtime deploys: shift traffic between old and new backends.

Application servers like gunicorn, Node or Tomcat are built to run application code, not to face the internet directly; the reverse proxy takes that job.

A working nginx configuration

nginx configuration is a tree of blocks. Put a file in /etc/nginx/conf.d/ (or sites-enabled/ on Debian/Ubuntu):

upstream app {
    server 127.0.0.1:9001;
}

server {
    listen 80;
    server_name shop.example.com;

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

Always check and reload without dropping connections:

sudo nginx -t              # test the configuration
sudo nginx -s reload       # or: sudo systemctl reload nginx

nginx -t output when fine: nginx: configuration file /etc/nginx/nginx.conf test is successful.

  • server blocks are virtual hosts. nginx picks one by the Host header (server_name) and the listen port.
  • location blocks match the request path. location /api/ { proxy_pass http://127.0.0.1:9001/; } sends /api/users to the backend as /users: a trailing slash on proxy_pass replaces the matched prefix, and without it the path is passed unchanged. This single slash causes many "404 from the backend" bugs.
  • proxy_pass names the backend: a URL or an upstream group.

What the backend sees, and the forwarding headers

By default, the backend sees the proxy's IP as the client and, unless you set it, Host as the upstream's address. We tested with a backend that prints the headers it received:

Host: 127.0.0.1
X-Real-IP: 127.0.0.1
X-Forwarded-For: 203.0.113.9, 127.0.0.1
X-Forwarded-Proto: http

Here the test client sent X-Forwarded-For: 203.0.113.9, and the proxy appended its own view of the client (127.0.0.1) using $proxy_add_x_forwarded_for. The headers you almost always want:

  • Host $host so the app knows which site was requested (needed for virtual hosts, redirects, absolute URLs).
  • X-Real-IP / X-Forwarded-For with the original client IP, for logs, rate limits and geolocation.
  • X-Forwarded-Proto $scheme so the app knows the client used HTTPS. Without it, frameworks build http:// links and cause redirect loops behind a TLS-terminating proxy.

Security note: X-Forwarded-For is just a header; a client can send a fake one. Only trust it from your own proxies, and configure the application (or nginx's real_ip_header and set_real_ip_from) accordingly. Use the rightmost entry your trusted proxy added, not the leftmost value the client claimed.

Timeouts, buffering and size limits

location / {
    proxy_pass http://app;
    proxy_connect_timeout 5s;     # time to establish a connection to the backend
    proxy_read_timeout    60s;    # time to wait between reads of the backend's response
    client_max_body_size  10m;    # reject larger uploads with 413
}

The defaults are 60 seconds for read. A long-running request (report generation) that exceeds proxy_read_timeout gets a 504. Raising timeouts hides slow endpoints; prefer asynchronous jobs for long work. Buffering is on by default, so slow clients do not hold backend workers; turn it off only for streaming.

WebSockets

WebSockets need the HTTP upgrade headers passed on and HTTP/1.1:

location /ws/ {
    proxy_pass http://app;
    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection "upgrade";
}

TLS at the proxy

server {
    listen 443 ssl http2;     # nginx 1.25.1 and newer: listen 443 ssl; plus the separate line http2 on;
    server_name shop.example.com;
    ssl_certificate     /etc/letsencrypt/live/shop.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/shop.example.com/privkey.pem;
    location / { proxy_pass http://app; proxy_set_header X-Forwarded-Proto https; }
}
server { listen 80; server_name shop.example.com; return 301 https://$host$request_uri; }

Use fullchain.pem (leaf plus intermediates) and keep the private key readable by root only. certbot --nginx can set this up for you.

Debugging 502 and 504

Symptom Meaning Check
502 Bad Gateway nginx could not get a valid response from the backend Is the backend running and listening on that address and port? ss -tlnp. error.log: connect() failed (111: Connection refused)
504 Gateway Timeout backend accepted but did not answer in time slow query or hang; raise proxy_read_timeout only after finding why
404 from the backend wrong path forwarded the trailing slash rule of proxy_pass
Redirect loops, wrong links app thinks it is HTTP forward X-Forwarded-Proto, configure the app to trust it
413 upload too large client_max_body_size

We reproduced a 502 by stopping the backend: curl got 502 and /var/log/nginx/error.log contained:

connect() failed (111: Connection refused) while connecting to upstream, client: 127.0.0.1, request: "GET / HTTP/1.1", upstream: "http://127.0.0.1:9001/"

The error log names the exact upstream it tried, which tells you which hop broke. Always check error.log first, then the backend's own log.

Common mistakes

  • Not forwarding Host and X-Forwarded-Proto, causing redirect loops and wrong URLs.
  • The proxy_pass trailing slash surprise.
  • Trusting X-Forwarded-For from anyone.
  • Editing the config without nginx -t.
  • Raising timeouts to hide a slow endpoint.
  • Exposing the backend port publicly, bypassing the proxy's TLS and rules. Bind backends to 127.0.0.1 or a private network.

Try it yourself

  1. Start python3 -m http.server 9001 --bind 127.0.0.1, install nginx, proxy port 8088 to it, and fetch it with curl.
  2. Stop the backend and capture the 502 and the matching line from error.log.
  3. Write a tiny backend that echoes the headers it receives, and confirm which X-Forwarded-* headers arrive.
  4. Add a second location /api/ that proxies to a different backend with and without a trailing slash, and compare the paths the backend receives.

Check yourself

What is the difference between a forward proxy and a reverse proxy?

A forward proxy acts for clients toward the internet. A reverse proxy acts for servers: clients connect to it and it forwards to backends.

Why must a TLS-terminating proxy send X-Forwarded-Proto?

The backend receives plain HTTP and cannot tell the client used HTTPS. Without the header it generates http:// URLs and redirects, causing mixed content or loops.

A request through nginx returns 504. Where do you look?

nginx's error.log (it says upstream timed out), then the backend's logs and performance: a slow query, an overloaded worker pool, or a hung dependency. Check proxy_read_timeout only afterwards.

How does the backend learn the real client IP?

From headers the proxy sets (X-Forwarded-For, X-Real-IP) or the PROXY protocol, trusted only from known proxies.

Interview questions

Why not expose the application server directly to the internet?

App servers are not built for TLS management, slow clients, attack filtering or static content. A reverse proxy handles those, enables routing and load balancing, and keeps backends on a private network.

What does proxy_pass http://app/; do differently from proxy_pass http://app; inside location /api/?

With a trailing slash the matched prefix /api/ is replaced by /, so /api/users becomes /users. Without it the original path /api/users is passed through.

How do you reload nginx configuration safely?

nginx -t to validate, then nginx -s reload (or systemctl reload nginx), which starts new workers with the new config and lets old ones finish their requests.

Summary

  • A reverse proxy fronts your servers: TLS termination, routing, load balancing, caching, protection.
  • Forward Host, X-Forwarded-For and X-Forwarded-Proto; trust them only from your own proxies.
  • Mind the proxy_pass trailing slash, timeouts, upload limits and WebSocket headers.
  • 502 means the backend is down or invalid, 504 means it is too slow; read nginx's error.log first.

Going deeper

See how much of this you can explain

A free mock interview asks you new questions on Networking for DevOps for DevOps Engineer and scores every answer, with what to fix.