Nginx

When to Use

User needs Nginx expertise — from basic server blocks to production configurations. Agent handles reverse proxy, SSL, caching, and performance tuning.

Quick Reference

Location Matching

• Exact = first, then ^~ prefix, then regex ~/~*, then longest prefix
• location /api matches /api, /api/, /api/anything — prefix match
• location = /api only matches exactly /api — not /api/
• location ~ \.php$ is regex, case-sensitive — ~* for case-insensitive
• ^~ stops regex search if prefix matches — use for static files

proxy_pass Trailing Slash

• proxy_pass http://backend preserves location path — /api/users → /api/users
• proxy_pass http://backend/ replaces location path — /api/users → /users
• Common mistake: missing slash = double path — or unexpected routing
• Test with curl -v to see actual backend request

try_files

• try_files $uri $uri/ /index.html for SPA — checks file, then dir, then fallback
• Last argument is internal redirect — or =404 for error
• $uri/ tries directory with index — set index index.html
• Don't use for proxied locations — use proxy_pass directly

Proxy Headers

• proxy_set_header Host $host — backend sees original host, not proxy IP
• proxy_set_header X-Real-IP $remote_addr — client IP, not proxy
• proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for — append to chain
• proxy_set_header X-Forwarded-Proto $scheme — for HTTPS detection

Upstream

• Define servers in upstream block — upstream backend { server 127.0.0.1:3000; }
• proxy_pass http://backend uses upstream — load balancing included
• Health checks with max_fails and fail_timeout — marks server unavailable
• keepalive 32 for connection pooling — reduces connection overhead

SSL/TLS

• ssl_certificate is full chain — cert + intermediates, not just cert
• ssl_certificate_key is private key — keep permissions restricted
• ssl_protocols TLSv1.2 TLSv1.3 — disable older protocols
• ssl_prefer_server_ciphers on — server chooses cipher, not client

Common Mistakes

• nginx -t before nginx -s reload — test config first
• Missing semicolon — syntax error, vague message
• root inside location — prefer in server, override only when needed
• alias vs root — alias replaces location, root appends location
• Variables in if — many things break inside if, avoid complex logic

Variables

• $uri is decoded, normalized path — /foo%20bar becomes /foo bar
• $request_uri is original with query string — unchanged from client
• $args is query string — $arg_name for specific parameter
• $host from Host header — $server_name from config

Performance