Deploying a Web App Behind Nginx
Most production web applications don't face the internet directly through their own framework's built-in server. Instead, an application server like Gunicorn, uWSGI, Node's http module, or Puma runs on localhost or a Unix socket, and Nginx sits in front of it, handling TLS termination, static file serving, compression, and connection management, then reverse-proxying dynamic requests to the app. This separation exists because most application frameworks' built-in servers are not designed to handle slow clients, thousands of concurrent connections, or serve static files efficiently — jobs Nginx does very well.
Cricket analogy: Nginx fronting an app server is like a team's opening batter absorbing the new-ball swing before handing over to the middle order, who can then focus purely on building the innings.
Reverse Proxying to an Application Server
The core directive is proxy_pass inside a location block, which forwards matching requests to your app server, typically over a Unix socket for lowest latency on the same host, or over TCP to 127.0.0.1:port. You should always forward proxy_set_header Host $host, X-Real-IP, and X-Forwarded-For and X-Forwarded-Proto so the application knows the original client IP and whether the original request was HTTPS, since from the app server's point of view every request now appears to come from Nginx on localhost. Timeouts (proxy_connect_timeout, proxy_read_timeout) should be tuned deliberately — the defaults are often too short for slow endpoints like report generation or file uploads.
Cricket analogy: Forwarding X-Forwarded-For so the app knows the real client IP is like a scorer noting which specific bowler delivered a wicket-taking ball, even though the captain formally reports the figures to the umpire.
TLS Termination and Static Assets
Nginx typically terminates TLS using a certificate from Let's Encrypt (often automated via certbot) or a commercial CA, configured with ssl_certificate and ssl_certificate_key, plus modern settings like ssl_protocols TLSv1.2 TLSv1.3 and a strong ssl_ciphers list. Static assets — JavaScript bundles, CSS, images — should be served directly by Nginx via a location block with root or alias rather than proxied to the app server, since Nginx serves files from disk far more efficiently and can add far-future expires headers and gzip or brotli compression, letting the application server spend its capacity exclusively on dynamic logic.
Cricket analogy: TLS termination at Nginx is like a stadium's single security gate checking every ticket before fans reach any stand, rather than each individual stand rechecking tickets separately.
certbot's nginx plugin can automatically edit your server blocks to add ssl_certificate directives and set up a redirect from port 80 to 443, plus a systemd timer for renewal — run sudo certbot --nginx -d example.com -d www.example.com and verify auto-renewal with sudo certbot renew --dry-run.
Process Management and Zero-Downtime Deploys
Nginx itself should run under systemd so it restarts automatically on crash and starts on boot, while your app server process (Gunicorn workers, a Node cluster, etc.) is typically managed by its own systemd unit or a process supervisor like pm2, separate from Nginx. For zero-downtime deploys, a common pattern starts a new app server instance on a new socket or port, waits for it to pass a health check, then reloads Nginx's upstream configuration or uses a blue-green upstream swap, so in-flight requests to the old instance finish gracefully before it's terminated — Nginx's own graceful reload (nginx -s reload) never drops connections mid-request, spawning new workers and letting old workers finish their current requests before exiting.
Cricket analogy: Nginx's graceful reload letting in-flight requests finish is like a substitute fielder coming on between overs rather than mid-delivery, never interrupting a ball actually in play.
Reloading Nginx (nginx -s reload) re-reads configuration and gracefully replaces worker processes, but it does not restart your upstream application server. If you change app code, you still need to restart or redeploy the app server process separately — a reload alone will keep proxying to the old running app process.
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;
ssl_protocols TLSv1.2 TLSv1.3;
root /var/www/example/public;
location /static/ {
alias /var/www/example/static/;
expires 30d;
add_header Cache-Control "public, immutable";
}
location / {
proxy_pass http://unix:/run/example-app.sock;
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;
proxy_read_timeout 60s;
}
}
server {
listen 80;
server_name example.com;
return 301 https://$host$request_uri;
}- Nginx should sit in front of the application server, handling TLS termination, static file serving, and connection management.
- proxy_pass forwards requests to the app over a Unix socket (lowest latency) or TCP loopback, with proxy_set_header preserving client IP, host, and scheme.
- Static assets should be served directly by Nginx via root/alias, not proxied, with cache headers and compression applied.
- certbot automates Let's Encrypt certificate issuance and renewal, typically integrating directly with Nginx server blocks.
- nginx -s reload gracefully swaps worker processes without dropping in-flight connections, but does not restart the backend app server.
- Zero-downtime deploys generally require a separate health-checked cutover of the app server, independent of Nginx's own reload mechanism.
- Default proxy timeouts are often too short for slow endpoints like file uploads or report generation and should be tuned explicitly.
Practice what you learned
1. Why is it recommended to serve static assets directly from Nginx rather than proxying them to the app server?
2. Which header tells the application the original request scheme (HTTP or HTTPS) when TLS is terminated at Nginx?
3. What does nginx -s reload NOT do?
4. Why might proxy_pass to a Unix socket be preferred over TCP loopback for a co-located app server?
5. What tool commonly automates both Let's Encrypt certificate issuance and Nginx TLS configuration?
Was this page helpful?
You May Also Like
Nginx vs Apache
A practical comparison of Nginx's event-driven architecture against Apache's process-based model, covering configuration philosophy, performance under load, and when to choose or combine each.
Nginx as an API Gateway
How to use Nginx to route, rate-limit, authenticate, and load balance API traffic across backend services without a dedicated gateway product.
Nginx Quick Reference
A condensed reference of essential Nginx commands, directives, and configuration patterns for daily operational use.
Related Reading
Related Study Notes in DevOps
Browse all study notesAnsible Study Notes
DevOps · 30 topics
DevOpsAdvanced Kubernetes Study Notes
Kubernetes · 30 topics
DevOpsAdvanced Bash Scripting Study Notes
Bash · 30 topics
DevOpsApache Kafka Study Notes
Kafka · 30 topics
DevOpsDocker & Kubernetes Study Notes
YAML · 40 topics
DevOpsCI/CD Tools & Pipelines Study Notes
YAML · 37 topics