liminfoNginx Reference
Free reference guide: Nginx Reference
About Nginx Reference
The Nginx Reference is a practical cheat sheet covering every major Nginx configuration directive used in production deployments. The server block section documents listen, server_name with wildcard and regex patterns, root and index directives, and custom error_page handling. Engineers can look up exactly how to define a virtual host, set document roots, and respond to 404/5xx errors without digging through the official documentation.
The location and proxy sections are the heart of the reference. Location blocks are covered with prefix matching, regex matching using ~, exact matching with =, and the try_files directive for single-page application routing. The proxy section shows proxy_pass configuration with proper header forwarding (Host, X-Real-IP, X-Forwarded-For, X-Forwarded-Proto), upstream server group definitions, and proxy_redirect. SSL/TLS configuration includes Let's Encrypt certificate paths, ssl_protocols limited to TLSv1.2 and TLSv1.3, cipher suite hardening, HTTP-to-HTTPS 301 redirects, and ssl_session_cache for performance.
Load balancing and caching round out the reference. The upstream module is documented with round-robin (default), least_conn for connection-aware routing, ip_hash for sticky sessions, and weighted backends using the weight= parameter. Cache configuration covers proxy_cache_path for disk-based caching, proxy_cache activation with per-status TTLs using proxy_cache_valid, browser-side expires headers for static assets, and Cache-Control header manipulation. This reference is used by DevOps engineers, system administrators, and backend developers deploying Node.js, Python, and PHP applications behind Nginx.
Key Features
- Server block directives — listen, server_name (wildcard and regex), root, index, error_page
- Location block variants — prefix, regex (~), exact (=), and try_files for SPA routing
- Reverse proxy setup — proxy_pass with Host, X-Real-IP, and X-Forwarded-For headers
- Upstream server groups with round-robin, least_conn, ip_hash, and weight= balancing
- SSL/TLS config — Let's Encrypt paths, TLSv1.2/1.3, cipher hardening, session cache
- HTTP to HTTPS 301 redirect with return 301 directive
- Proxy caching with proxy_cache_path, proxy_cache_valid, and per-status TTL control
- Browser caching with expires directive and Cache-Control header for static assets
Frequently Asked Questions
What is a server block in Nginx and how does it work?
A server block is the Nginx equivalent of an Apache VirtualHost. It defines how Nginx handles requests for a specific domain or IP:port combination. Nginx selects the matching server block by comparing the Host header to server_name values. You can have multiple server blocks in the same config to host several domains on one server. Each block contains its own root, listen, and location directives.
How do I configure Nginx as a reverse proxy for a Node.js app?
Use the proxy_pass directive inside a location block pointing to your app's local port. Always include proxy_set_header directives to forward the Host, X-Real-IP, and X-Forwarded-For headers so your app can identify the original client. For example: location / { proxy_pass http://localhost:3000; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; }. Add proxy_http_version 1.1 and proxy_set_header Upgrade/Connection for WebSocket support.
What is the difference between proxy_pass and try_files?
proxy_pass forwards the request to a backend server (like Node.js or PHP-FPM). try_files checks whether a file or directory exists on disk and serves it directly, falling back to a final URI or status code if nothing is found. try_files is ideal for single-page applications: try_files $uri $uri/ /index.html serves the index.html for all routes that do not match a static file.
How do I set up SSL with Let's Encrypt in Nginx?
Run certbot --nginx to automatically obtain and configure certificates, or configure manually by setting ssl_certificate to the fullchain.pem path and ssl_certificate_key to privkey.pem. Add a separate HTTP server block that returns a 301 redirect to HTTPS. Set ssl_protocols to TLSv1.2 TLSv1.3 and configure ssl_ciphers to exclude weak algorithms. Enable ssl_session_cache shared:SSL:10m to improve handshake performance for returning clients.
How does Nginx load balancing work?
Define an upstream block with multiple server entries. By default Nginx uses round-robin, distributing each new request to the next server in sequence. Use least_conn to route to whichever backend has the fewest active connections — better for long-lived requests. Use ip_hash to ensure the same client IP always reaches the same backend, which is useful for session affinity. Add weight=N to send proportionally more traffic to stronger servers.
How do I enable proxy caching in Nginx?
First define a cache zone with proxy_cache_path specifying the directory, key zone name, and maximum size. Then activate the cache in a location block with proxy_cache and set per-status expiry with proxy_cache_valid 200 60m to cache 200 responses for 60 minutes. Use proxy_cache_bypass and proxy_no_cache directives to skip caching for authenticated or dynamic requests. Add add_header X-Cache-Status $upstream_cache_status to debug cache hits.
What does the Nginx rewrite directive do?
The rewrite directive changes the URI of a request using a regular expression and a replacement string. The last flag stops processing further rewrite rules and restarts the location matching, while permanent issues a 301 redirect to the client. Use rewrite sparingly; for simple redirects, return 301 /new-path is faster because it skips the regex engine. For complex URL migrations, rewrite provides the flexibility to capture groups and reconstruct URLs.
How do I configure Nginx to serve a single-page application?
Use try_files $uri $uri/ /index.html inside the root location block. This tells Nginx to first check whether the exact file exists, then whether a directory index exists, and finally serve index.html — letting the client-side router handle the path. Make sure your API routes are matched by a separate more-specific location block before the catch-all, so that API requests are proxied to the backend rather than returning index.html.