Lesson 9 of 14 · 10 min · HTTP, TLS and traffic management
Reverse proxies with nginx
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_passand 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.
serverblocks are virtual hosts. nginx picks one by theHostheader (server_name) and the listen port.locationblocks match the request path.location /api/ { proxy_pass http://127.0.0.1:9001/; }sends/api/usersto the backend as/users: a trailing slash onproxy_passreplaces the matched prefix, and without it the path is passed unchanged. This single slash causes many "404 from the backend" bugs.proxy_passnames the backend: a URL or anupstreamgroup.
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 $hostso the app knows which site was requested (needed for virtual hosts, redirects, absolute URLs).X-Real-IP/X-Forwarded-Forwith the original client IP, for logs, rate limits and geolocation.X-Forwarded-Proto $schemeso the app knows the client used HTTPS. Without it, frameworks buildhttp://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
HostandX-Forwarded-Proto, causing redirect loops and wrong URLs. - The
proxy_passtrailing slash surprise. - Trusting
X-Forwarded-Forfrom 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.1or a private network.
Try it yourself
- Start
python3 -m http.server 9001 --bind 127.0.0.1, install nginx, proxy port 8088 to it, and fetch it withcurl. - Stop the backend and capture the 502 and the matching line from
error.log. - Write a tiny backend that echoes the headers it receives, and confirm which
X-Forwarded-*headers arrive. - 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-ForandX-Forwarded-Proto; trust them only from your own proxies. - Mind the
proxy_passtrailing 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.logfirst.
Going deeper
- nginx: ngx_http_proxy_module: all
proxy_*directives. - nginx beginner's guide: configuration structure and a first proxy.
- NGINX reverse proxy documentation: admin guide to proxying.
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.