Deploying a Web App Behind Nginx

Analogy categoryAnalogies

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.

nginx

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.