Nginx Config skill for Codex

A good Nginx config is small, tested with nginx -t before every reload, passes the original host, scheme and client IP to the app, terminates TLS with modern defaults, and avoids the traps that only show in production: proxy_pass slash rewriting, add_header inheritance, and if inside location.

Inspect first

1. Find the layout: nginx -V 2>&1 | tr ' ' '\n' | grep -E 'conf-path|with-http_v2|with-http_v3' and nginx -T to dump the full effective config (includes resolved).
2. Note the version (nginx -v). http2 on; needs 1.25.1+; older versions use listen 443 ssl http2;.
3. Identify what sits in front (cloud load balancer, CDN) and behind (app port, socket).
4. Read AGENTS.md for the app’s health endpoint and whether it expects X-Forwarded-Proto to build URLs.

Reverse proxy baseline

upstream app {
    server 127.0.0.1:3000;
    keepalive 32;
}

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

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    location /.well-known/acme-challenge/ { root /var/www/acme; }
    location / { return 301 https://example.com$request_uri; }
}

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_session_cache shared:SSL:10m;
    ssl_session_timeout 1d;
    add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;

    client_max_body_size 20m;

    location / {
        proxy_pass http://app;
        proxy_http_version 1.1;
        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_set_header Upgrade           $http_upgrade;
        proxy_set_header Connection        $connection_upgrade;
        proxy_read_timeout 60s;
    }
}

• keepalive in the upstream only works with proxy_http_version 1.1 and a Connection header that is not close; the map sends an empty value for normal requests.
• Start HSTS with a short max-age (300) when the site is new to HTTPS; add preload only when every subdomain serves HTTPS permanently.
• Let’s Encrypt stopped OCSP responses in 2025, so ssl_stapling does nothing for its certificates; leave it off.

proxy_pass slash rules

location	proxy_pass	Request /api/users reaches upstream as
/api/	http://app	/api/users (URI passed unchanged)
/api/	http://app/	/users (location prefix replaced by /)
/api/	http://app/v2/	/v2/users
/api	http://app/	//users (double slash: match prefix and path slashes)

A variable in proxy_pass (proxy_pass http://$backend;) disables this rewriting and requires a resolver directive for hostnames.

Real client IP behind a load balancer

set_real_ip_from 10.0.0.0/8;          # your LB or CDN ranges only
real_ip_header X-Forwarded-For;
real_ip_recursive on;

Never trust X-Forwarded-For from everywhere; any client can forge it. For Cloudflare, use its published IP ranges and CF-Connecting-IP.

Rate limiting

# http context
limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;
limit_req_zone $binary_remote_addr zone=login:10m rate=5r/m;
limit_req_status 429;

# server or location
location /api/   { limit_req zone=api burst=20 nodelay; proxy_pass http://app; }
location = /login { limit_req zone=login burst=5; proxy_pass http://app; }

• 10 MB of zone holds about 160,000 IPv4 states.
• Behind a load balancer without the real-IP block above, every client shares the LB’s address and one user exhausts the limit for everyone.
• Use limit_req_dry_run on; first to log what would be rejected.

Caching

# http context
proxy_cache_path /var/cache/nginx/app levels=1:2 keys_zone=appcache:50m max_size=2g inactive=60m use_temp_path=off;

location /public/ {
    proxy_cache appcache;
    proxy_cache_valid 200 301 10m;
    proxy_cache_use_stale error timeout updating http_500 http_502 http_503;
    proxy_cache_lock on;
    add_header X-Cache-Status $upstream_cache_status always;
    proxy_pass http://app;
}

location ~* \.(?:js|css|woff2|png|jpg|svg|webp)$ {
    root /var/www/app/dist;
    expires 1y;
    add_header Cache-Control "public, immutable" always;
}

• Nginx does not cache responses carrying Set-Cookie or Cache-Control: private; that is usually correct. Never cache authenticated pages by ignoring those headers.
• immutable only for fingerprinted filenames.

Common locations

location / { try_files $uri $uri/ /index.html; }          # SPA fallback (static root)

location /events/ {                                       # Server-Sent Events
    proxy_pass http://app;
    proxy_http_version 1.1;
    proxy_set_header Connection '';
    proxy_buffering off;
    proxy_read_timeout 1h;
}

location = /healthz { access_log off; proxy_pass http://app; }

Hard rules

• add_header in a location discards every add_header from the parent level. Repeat security headers in each location that adds its own, or put them in an included snippet.
• Use always on headers that must appear on error responses too.
• Avoid if in location except for return and rewrite ... last; use map instead.
• server_name _; default server should return 444; so unknown Host headers do not hit the app.
• Do not expose /.git, .env or backup files from a static root: location ~ /\.(?!well-known) { deny all; }.

Debugging

Symptom	Check
502 Bad Gateway	App down or wrong port; error_log shows connect() failed; SELinux httpd_can_network_connect
504 Gateway Timeout	Slow upstream; raise proxy_read_timeout only after confirming the app is not stuck
Redirect loop	App sees http because X-Forwarded-Proto missing, redirects to https forever
413 Request Entity Too Large	client_max_body_size
Wrong client IP in app logs	Missing real-IP config or proxy headers
Old config still served	Reload failed silently; run nginx -t and check systemctl status nginx

curl -sv -H 'Host: example.com' https://127.0.0.1/ -k tests a vhost locally; curl -I shows headers.

Apply

sudo nginx -t && sudo systemctl reload nginx

reload keeps existing connections; restart drops them. On a production host, show the diff and the nginx -t result and get the user’s confirmation before reloading.

Verification

• nginx -t passes; nginx -T shows the intended effective config.
• curl -I http://example.com returns 301 to https; curl -I https://example.com shows HSTS and expected headers.
• openssl s_client -connect example.com:443 -servername example.com </dev/null shows TLS 1.3 and the full chain.
• App logs show real client IPs; a burst test returns 429 at the configured rate.