Nginx, properly: architecture, config patterns, and the 2026 landscape

master process        # reads config, binds ports, manages workers - runs as root
├── worker process    # handles connections - runs as an unprivileged user
├── worker process
├── worker process
├── worker process    # one per CPU core by default
├── cache manager     # evicts expired cache entries
└── cache loader      # loads cache metadata at startup, then exits

# main context - worker processes, user, error log, pid file
user  nginx;
worker_processes  auto;
error_log  /var/log/nginx/error.log warn;

events {
    worker_connections  4096;
}

http {
    # applies to every server below unless overridden
    include       /etc/nginx/mime.types;
    default_type  application/octet-stream;
    sendfile      on;
    keepalive_timeout  65;

    server {
        listen 443 ssl;
        server_name example.com;

        location /api/ {
            proxy_pass http://backend;
        }
    }
}

stream {
    # raw TCP and UDP proxying - a separate world from http
}

server {
    add_header X-Frame-Options DENY;
    add_header X-Content-Type-Options nosniff;

    location /api/ {
        add_header X-API-Version 2;
        # X-Frame-Options and X-Content-Type-Options are NOT sent here.
        # The location's add_header directives replaced the server's entirely.
    }
}

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;

    root /var/www/example.com;
    index index.html;

    # SPA fallback: try the file, then the directory, then hand to index.html
    location / {
        try_files $uri $uri/ /index.html;
    }

    # Hashed assets can be cached forever
    location ~* \.(?:css|js|woff2|png|jpg|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
        access_log off;
    }

    # Never cache the HTML entry point
    location = /index.html {
        add_header Cache-Control "no-cache";
    }
}

upstream app {
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;

    # Reuse connections to the backend - without this every request
    # opens a new TCP connection, which is a large hidden cost
    keepalive 32;
}

server {
    listen 443 ssl;
    http2 on;
    server_name example.com;

    location / {
        proxy_pass http://app;

        # Required for keepalive to the upstream to work at all
        proxy_http_version 1.1;
        proxy_set_header Connection "";

        # Without these your app sees nginx's IP and thinks every request is HTTP
        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_connect_timeout 5s;
        proxy_send_timeout    60s;
        proxy_read_timeout    60s;
    }
}

map $http_upgrade $connection_upgrade {
    default upgrade;
    ''      close;
}

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

    proxy_read_timeout 3600s;   # otherwise idle sockets die after 60s
}

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    http2 on;
    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;
    ssl_prefer_server_ciphers off;   # let the client choose; modern clients pick well
    ssl_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    ssl_session_tickets off;

    ssl_stapling on;
    ssl_stapling_verify on;
    resolver 1.1.1.1 8.8.8.8 valid=300s;

    add_header Strict-Transport-Security "max-age=63072000" always;
}

server {
    listen 80;
    server_name example.com;
    return 301 https://$host$request_uri;
}

location /images/ {
    root /var/www/static;          # never reached for .png files
}

location ~* \.(png|jpg)$ {
    expires 30d;                   # this wins - regex beats plain prefix
}

# To make the prefix win, use ^~ which stops the regex search
location ^~ /images/ {
    root /var/www/static;          # now this handles /images/logo.png
}

# WITHOUT a trailing slash: the full original URI is passed through
location /api/ {
    proxy_pass http://backend;
}
# request /api/users  →  backend receives /api/users

# WITH a trailing slash: the location prefix is stripped and replaced
location /api/ {
    proxy_pass http://backend/;
}
# request /api/users  →  backend receives /users

upstream app {
    # Default is round robin. Alternatives:
    least_conn;              # send to the server with fewest active connections
    # hash $request_uri consistent;   # consistent hashing, good for cache nodes
    # ip_hash;                        # sticky by client IP

    server 10.0.1.10:3000 weight=3;
    server 10.0.1.11:3000;
    server 10.0.1.12:3000 backup;      # only used when the others are down

    # Passive health checks: mark down after 3 failures in 30s
    server 10.0.1.13:3000 max_fails=3 fail_timeout=30s;

    keepalive 32;
}

location / {
    proxy_pass http://app;

    # Retry the next upstream on these conditions
    proxy_next_upstream error timeout http_502 http_503;
    proxy_next_upstream_tries 2;
    proxy_next_upstream_timeout 10s;
}

# In the http context
proxy_cache_path /var/cache/nginx
    levels=1:2
    keys_zone=app_cache:100m      # 100MB holds roughly 800k keys
    max_size=10g
    inactive=60m
    use_temp_path=off;

location / {
    proxy_cache app_cache;
    proxy_cache_key "$scheme$request_method$host$request_uri";

    proxy_cache_valid 200 301 302 10m;
    proxy_cache_valid 404 1m;

    # Serve stale content rather than an error while revalidating
    proxy_cache_use_stale error timeout updating http_500 http_502 http_503;
    proxy_cache_background_update on;

    # One request refreshes the entry; the rest wait rather than stampeding
    proxy_cache_lock on;
    proxy_cache_lock_timeout 5s;

    # Never cache a response for a logged-in user
    proxy_cache_bypass $cookie_session $http_authorization;
    proxy_no_cache     $cookie_session $http_authorization;

    add_header X-Cache-Status $upstream_cache_status always;

    proxy_pass http://app;
}

# In the http context. $binary_remote_addr is compact - 16 bytes per IPv6 entry
limit_req_zone  $binary_remote_addr zone=general:10m rate=30r/s;
limit_req_zone  $binary_remote_addr zone=login:10m   rate=5r/m;
limit_conn_zone $binary_remote_addr zone=conns:10m;

# Return 429 rather than the default 503 - clients understand it better
limit_req_status  429;
limit_conn_status 429;

server {
    location / {
        limit_req  zone=general burst=60 nodelay;
        limit_conn conns 20;
        proxy_pass http://app;
    }

    location = /auth/login {
        limit_req zone=login burst=3;   # no nodelay: queue them, slow them down
        proxy_pass http://app;
    }
}

# Trust the CDN's forwarded address - list only ranges you control
set_real_ip_from 173.245.48.0/20;
set_real_ip_from 103.21.244.0/22;
real_ip_header   CF-Connecting-IP;
real_ip_recursive on;

# Check your running version
nginx -v

# Find rewrite rules with unnamed captures and a question mark
grep -rnE 'rewrite .*\$[0-9].*\?' /etc/nginx/

# Named captures are a mitigation as well as better style
# vulnerable pattern:  rewrite ^/api/(.*)$ /internal?id=$1;
# safer:               rewrite ^/api/(?<path>.*)$ /internal?id=$path;

server_tokens off;                    # stop advertising the exact version

# Size limits - the cheapest DoS protection there is
client_max_body_size      10m;
client_body_buffer_size   128k;
client_header_buffer_size 1k;
large_client_header_buffers 4 8k;

# Slowloris protection
client_body_timeout   10s;
client_header_timeout 10s;
send_timeout          10s;

# Security headers - repeat these in any location that sets its own
add_header X-Content-Type-Options    nosniff always;
add_header X-Frame-Options           SAMEORIGIN always;
add_header Referrer-Policy           strict-origin-when-cross-origin always;
add_header Strict-Transport-Security "max-age=63072000" always;

# Block access to hidden files, but keep ACME challenges working
location ~ /\.(?!well-known) {
    deny all;
}

worker_processes auto;                # one per core
worker_rlimit_nofile 65535;           # raise the file descriptor limit

events {
    worker_connections 8192;          # per worker: 4 cores × 8192 ≈ 32k connections
    multi_accept on;
}

http {
    sendfile    on;                   # kernel-space file transfer, no user-space copy
    tcp_nopush  on;                    # fill packets before sending
    tcp_nodelay on;                    # but do not delay the last one

    keepalive_timeout  65;
    keepalive_requests 1000;

    open_file_cache max=10000 inactive=30s;
    open_file_cache_valid 60s;
    open_file_cache_min_uses 2;
    open_file_cache_errors on;

    gzip on;
    gzip_vary on;
    gzip_comp_level 5;
    gzip_min_length 256;
    gzip_types text/plain text/css application/json application/javascript
               application/xml image/svg+xml;
}

# Default: buffering on. Good for normal responses.
proxy_buffering on;
proxy_buffer_size 8k;
proxy_buffers 16 8k;
proxy_busy_buffers_size 16k;

# Turn it OFF for streaming: Server-Sent Events, LLM token streams, log tailing
location /events/ {
    proxy_pass http://app;
    proxy_buffering off;
    proxy_cache off;
    proxy_read_timeout 3600s;
    add_header X-Accel-Buffering no;
}

# Always test before reloading - this catches syntax errors and bad paths
nginx -t

# Reload without dropping connections: old workers finish their requests
nginx -s reload

# See the fully assembled config with every include expanded
nginx -T

# What was it compiled with?
nginx -V

# Which config file is actually in use?
nginx -V 2>&1 | grep -o 'conf-path=[^ ]*'

log_format detailed '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    'rt=$request_time uct=$upstream_connect_time '
                    'uht=$upstream_header_time urt=$upstream_response_time '
                    'cache=$upstream_cache_status host=$host '
                    '"$http_referer" "$http_user_agent"';

access_log /var/log/nginx/access.log detailed;

# Debug logging for one client IP only, without flooding the log
events {
    debug_connection 203.0.113.42;
}
error_log /var/log/nginx/debug.log debug;

# A default server that rejects unmatched hosts rather than leaking one
server {
    listen 443 ssl default_server;
    server_name _;
    ssl_certificate     /etc/nginx/ssl/default.crt;
    ssl_certificate_key /etc/nginx/ssl/default.key;
    return 444;   # nginx-specific: close the connection without a response
}