Nginx Cheatsheet — 80+ Configs and Commands with Real Examples and Gotchas

Test the current configuration files for syntax errors without reloading nginx.

⚠ Common pitfall: Run this BEFORE every reload. A typo plus a blind reload can take production down in two seconds.

nginx -t

sudo nginx -t

nginx -t -c /etc/nginx/nginx.conf

Reload the configuration without dropping in-flight connections (graceful, zero downtime).

⚠ Common pitfall: Reload silently keeps the old config if the new one fails to parse. Always pair with `nginx -t` first.

sudo nginx -s reload

sudo systemctl reload nginx

nginx -t && nginx -s reload

Fast shutdown — close listening sockets and kill workers immediately.

⚠ Common pitfall: `stop` cuts in-flight requests. For graceful shutdown use `nginx -s quit` instead.

sudo nginx -s stop

sudo systemctl stop nginx

Graceful shutdown — workers finish in-flight requests then exit.

sudo nginx -s quit

Reopen log files. Use this AFTER logrotate moves access.log / error.log, so nginx writes to the new files.

⚠ Common pitfall: Without `reopen`, nginx keeps writing to the rotated (now-deleted-by-name) file descriptor and disk fills up silently.

sudo nginx -s reopen

postrotate
    /usr/sbin/nginx -s reopen
endscript

Print nginx version, build options, and every module compiled in. Capital V — small v is just the version.

⚠ Common pitfall: Use `-V` to confirm an obscure module (`--with-http_v2_module`, `--with-http_realip_module`) is actually built in before you spend an hour debugging "directive unknown".

nginx -V

nginx -V 2>&1 | tr -- - "\n" | grep _module

Test the config AND dump the fully-resolved, all-includes-merged config to stdout. Best way to see what nginx actually sees.

sudo nginx -T

sudo nginx -T | grep server_name

sudo nginx -T > /tmp/nginx-full.conf

Start nginx with an alternative config file (handy when testing a candidate config out-of-tree).

nginx -c /tmp/nginx-test.conf

nginx -t -c /tmp/nginx-test.conf

Override the install prefix at runtime — useful for running nginx as a non-root user from a checkout.

nginx -p $(pwd) -c $(pwd)/nginx.conf

On systemd hosts, check the running state, recent logs, and last exit reason of the nginx service.

sudo systemctl status nginx

sudo systemctl restart nginx

sudo journalctl -u nginx -n 100 --no-pager

Inject global config directives from the command line, before the config file is read. Handy for one-off overrides.

⚠ Common pitfall: Each directive must end with a semicolon and the whole thing is one quoted argument: `nginx -g "daemon off;"`. Used a lot to run nginx in the foreground inside Docker.

nginx -g "daemon off;"

nginx -g "worker_processes 2;"

nginx -g "daemon off; master_process off;"

The reload signal is plain SIGHUP. `nginx -s reload` and `kill -HUP <master_pid>` do exactly the same thing.

kill -HUP $(cat /run/nginx.pid)

nginx -s reload

kill -HUP `cat /run/nginx.pid`

SIGUSR1 tells the master to reopen log files. Identical to `nginx -s reopen`; logrotate scripts often send it directly.

kill -USR1 $(cat /run/nginx.pid)

kill -USR1 `pidof -s nginx`

SIGUSR2 starts a new master from a new nginx binary without dropping connections. The classic zero-downtime binary upgrade.

⚠ Common pitfall: After USR2 you have two masters. Send WINCH to the old master to drain its workers, verify, then QUIT the old master. Roll back by HUP-ing the old one if the new binary misbehaves.

kill -USR2 $(cat /run/nginx.pid)

# old pid file becomes nginx.pid.oldbin
kill -WINCH $(cat /run/nginx.pid.oldbin)
kill -QUIT $(cat /run/nginx.pid.oldbin)

Print just the nginx version string. Lowercase v — capital V also dumps build options and modules.

nginx -v

nginx -v 2>&1

Suppress non-error messages during configuration testing. Pair with -t for quiet CI checks.

nginx -t -q

nginx -tq && nginx -s reload

Override the error-log path at startup (nginx ≥ 1.19.5). Useful when the default log path is not yet writable.

nginx -e /dev/stderr -g "daemon off;"

nginx -t -e stderr

Number of worker processes. `auto` matches the CPU core count and is the right answer almost always.

⚠ Common pitfall: Setting it higher than the core count adds context-switch overhead and gives ZERO extra throughput.

worker_processes auto;

worker_processes 4;

Max concurrent connections per worker. Total cap ≈ worker_processes × worker_connections.

⚠ Common pitfall: If you also raise this, raise the OS file-descriptor limit (`worker_rlimit_nofile` and systemd `LimitNOFILE`) or nginx logs "too many open files".

events {
    worker_connections 1024;
}

events {
    worker_connections 10240;
    multi_accept on;
    use epoll;
}

Block for connection-handling settings: worker_connections, multi_accept, use (epoll/kqueue).

events {
    worker_connections 1024;
    use epoll;
    multi_accept on;
}

Top-level block for HTTP-server settings, MIME types, gzip, upstream pools, server blocks.

http {
    include /etc/nginx/mime.types;
    sendfile on;
    keepalive_timeout 65;
    include /etc/nginx/conf.d/*.conf;
}

Include another config file (glob patterns supported). Standard way to split vhosts.

⚠ Common pitfall: Include order matters when directives override each other. `include conf.d/*.conf` loads alphabetically, so `00-default.conf` runs first.

include /etc/nginx/mime.types;

include /etc/nginx/conf.d/*.conf;

include /etc/nginx/sites-enabled/*;

OS user that worker processes run as. Master runs as root, workers drop to this user.

⚠ Common pitfall: If nginx workers cannot read your static files you usually see "Permission denied" in error.log. Check ownership against this user.

user www-data;

user nginx;

user nobody nogroup;

Path where nginx writes the master PID — used by `nginx -s` signals.

pid /run/nginx.pid;

pid /var/run/nginx.pid;

Use the kernel sendfile() syscall — zero-copy from disk to socket. Big win for static files.

⚠ Common pitfall: Disable sendfile in VirtualBox shared folders or some old NFS mounts — files come up corrupted otherwise.

sendfile on;

sendfile on;
tcp_nopush on;
tcp_nodelay on;

How long an idle keep-alive connection stays open (seconds). 65 covers the default 60s browser timer plus jitter.

keepalive_timeout 65;

keepalive_timeout 75s;

Max request body size (uploads). Default 1m. Set on http, server, or location.

⚠ Common pitfall: Hit a 413 Request Entity Too Large on upload? It is this. Set high enough or upgrade to streaming uploads.

client_max_body_size 10m;

client_max_body_size 100m;

client_max_body_size 0;  # unlimited

Raise the per-worker file-descriptor limit. Required when you bump worker_connections.

worker_rlimit_nofile 65535;

Let each worker accept all new connections at once instead of one per event-loop pass. Off by default.

⚠ Common pitfall: It helps under bursty connection storms but can mildly hurt latency under steady load. Measure before turning it on in production.

events {
    multi_accept on;
    worker_connections 4096;
}

Pick the connection-processing method. `epoll` on Linux, `kqueue` on BSD/macOS. nginx auto-detects, so set it only to be explicit.

events { use epoll; }

events { use kqueue; }  # BSD / macOS

Send response headers and the start of a file in one packet (Linux TCP_CORK). Only effective when sendfile is on.

sendfile on;
tcp_nopush on;

Disable Nagle’s algorithm on keep-alive connections so small responses go out immediately. On by default.

tcp_nodelay on;

Hide the nginx version number from error pages and the Server response header. A cheap, standard hardening step.

⚠ Common pitfall: This hides the version but does not remove the `Server: nginx` header itself. To drop the header entirely you need the headers-more module or a build patch.

http {
    server_tokens off;
}

Sizing for the MIME-type hash table. nginx itself tells you to raise it in a startup warning when you add many custom types.

types_hash_max_size 2048;
types_hash_bucket_size 128;

Fallback Content-Type when nginx cannot guess it from the file extension. octet-stream means "download me".

include /etc/nginx/mime.types;
default_type application/octet-stream;

Max idle time between two reads of the request body. A slow-upload client that stalls longer gets a 408.

client_body_timeout 12s;
client_header_timeout 12s;
send_timeout 10s;

Number and size of buffers for large request headers. Raise it when long cookies or URLs trigger 400 / 414.

⚠ Common pitfall: A request line longer than the buffer size gives 414 Request-URI Too Large; oversized headers give 400. Both point here, not at client_max_body_size.

large_client_header_buffers 4 16k;

client_header_buffer_size 1k;
large_client_header_buffers 4 8k;

DNS resolver nginx uses to resolve names at runtime (upstreams given as variables, OCSP, auth_request). Cache each answer for `valid`.

⚠ Common pitfall: Without a `resolver`, `proxy_pass https://$backend` with a variable host fails with "no resolver defined". A literal hostname is resolved once at startup and does not need it.

resolver 1.1.1.1 8.8.8.8 valid=300s ipv6=off;
resolver_timeout 5s;

Defines one virtual host. Multiple server blocks let one nginx serve many domains on the same port.

server {
    listen 80;
    server_name example.com;
    root /var/www/example;
}

Port (and optionally address + flags) this server block accepts on. Add `default_server` to handle requests for unknown hosts.

⚠ Common pitfall: Exactly ONE server per port can be `default_server`. Two defaults = nginx -t fails. Forgetting it = first server alphabetically wins.

listen 80;

listen 443 ssl http2;

listen 80 default_server;

listen [::]:80;  # IPv6

Which Host header(s) this server block answers. Supports wildcards (*.example.com) and regex (~^api\..+$).

⚠ Common pitfall: Wildcard server_names cannot start AND end with `*` (e.g. `*.example.*` is invalid). Regex names must start with `~`.

server_name example.com;

server_name example.com www.example.com;

server_name *.example.com;

server_name ~^(?<sub>.+)\.example\.com$;

Document root for this server / location. Set once at server level, override in specific locations if needed.

root /var/www/html;

root /home/user/site/public;

List of default files to serve when the URI maps to a directory. First one that exists wins.

index index.html;

index index.html index.htm index.php;

Listen on 443 with TLS and HTTP/2. The single line that turns on both for a server block.

⚠ Common pitfall: On nginx ≥ 1.25 prefer the newer form: `listen 443 ssl;` plus `http2 on;` directive — the inline `http2` is deprecated in newer builds.

listen 443 ssl http2;

listen 443 ssl;
http2 on;

listen [::]:443 ssl http2;

Drop the connection without sending a response. Useful for dropping requests with the wrong Host header.

# Catch-all server that drops unknown hosts
server {
    listen 80 default_server;
    server_name _;
    return 444;
}

Enable SO_REUSEPORT so the kernel load-balances new connections across workers. Reduces lock contention at high connection rates.

⚠ Common pitfall: Set `reuseport` on only ONE listen directive per address:port. Repeating it on a second server block for the same socket fails to start.

listen 80 reuseport;

listen 443 ssl reuseport;

Listen on a Unix domain socket instead of a TCP port. Common for an internal nginx fronted by another nginx or HAProxy on the same host.

listen unix:/run/nginx-internal.sock;

The "invalid" catch-all name. It matches no real Host header, so combined with default_server it handles everything that no named server claimed.

⚠ Common pitfall: `_` is not a wildcard — it only works as a catch-all because it can never match. The actual catch-all behaviour comes from `default_server` on the listen line.

server {
    listen 80 default_server;
    server_name _;
    return 444;
}

Make nginx emit relative Location headers on auto-redirects (e.g. adding a trailing slash) instead of absolute URLs with the wrong host/port.

⚠ Common pitfall: Behind a proxy that terminates TLS, nginx’s auto-redirect can send `http://internal:8080/path/`. Either set this off, or set `port_in_redirect off` and a correct `server_name`.

absolute_redirect off;

port_in_redirect off;
server_name_in_redirect off;

By default nginx collapses `//` in a URI to `/`. Turn merging off when a backend genuinely needs the double slash preserved.

⚠ Common pitfall: Turning it off changes how location prefixes match — test your routing afterward. Most apps want the default `on`.

merge_slashes off;

Prefix match — matches any URI that starts with the given string. The default catch-all.

location / {
    try_files $uri $uri/ /index.html;
}

Exact match (=). Highest priority — when the URI matches exactly, nginx stops searching immediately.

⚠ Common pitfall: Use `=` on hot endpoints like `/healthz` or `/` to skip the whole regex-location scan and save real CPU on busy hosts.

location = /healthz {
    return 200 "ok";
    access_log off;
}

location = / {
    return 301 /home;
}

Prefix match with preferential override (^~). If this prefix matches, nginx will NOT try any regex locations.

location ^~ /static/ {
    alias /var/www/site/static/;
    expires 30d;
}

Case-SENSITIVE regex match (~). For case-insensitive use `~*` instead.

location ~ \.php$ {
    fastcgi_pass unix:/run/php/php-fpm.sock;
    fastcgi_index index.php;
    include fastcgi_params;
}

Case-INSENSITIVE regex match (~*). Standard pattern for image caching.

location ~* \.(jpg|jpeg|png|gif|webp|svg|ico)$ {
    expires 30d;
    add_header Cache-Control "public, immutable";
}

Order: 1) exact `=` 2) longest `^~` prefix 3) first matching regex (~ / ~*) in file order 4) longest plain prefix.

⚠ Common pitfall: Regex order matters — first match wins, not "best" or "longest". Reorder regex locations to fix surprises.

# Tested order:
location = / { ... }              # 1 exact
location ^~ /static/ { ... }       # 2 ^~ prefix
location ~* \.(jpg|png)$ { ... }   # 3 regex (first match)
location / { ... }                 # 4 plain prefix (fallback)

A location named with @ is reachable only via internal redirects (try_files last arg, error_page). It never matches an external URI directly.

location / {
    try_files $uri $uri/ @app;
}

location @app {
    proxy_pass http://backend;
}

Mark a location as reachable only from inside nginx (internal redirects, X-Accel-Redirect, error_page). External requests get 404.

location /protected/ {
    internal;
    alias /var/www/private/;
}

location /download/ {
    internal;
    root /data;
}

Let your app authorize a download, then hand the file off to nginx via an internal location. nginx streams it with sendfile; the app never touches the bytes.

⚠ Common pitfall: The target location MUST be marked `internal;` or anyone could fetch the file directly and bypass your auth check.

# nginx side
location /protected-files/ {
    internal;
    alias /var/secure/;
}

# app returns header after auth:
#   X-Accel-Redirect: /protected-files/report.pdf

Allow or deny by client IP / CIDR. Rules are checked top to bottom; the first match wins. End an allow-list with `deny all`.

⚠ Common pitfall: Behind a proxy, `$remote_addr` is the proxy IP — these rules see the wrong address. Pair with the realip module so they match the true client.

location /admin/ {
    allow 10.0.0.0/8;
    allow 192.168.1.0/24;
    deny all;
}

HTTP Basic auth. Point auth_basic_user_file at an htpasswd file. Simple gate for staging or an admin path.

⚠ Common pitfall: Basic auth sends the password base64-encoded, not encrypted — only use it over HTTPS. Generate the file with `htpasswd -c /etc/nginx/.htpasswd user`.

location /admin/ {
    auth_basic "Restricted";
    auth_basic_user_file /etc/nginx/.htpasswd;
}

Delegate authorization to a subrequest. nginx calls the auth endpoint first; 2xx lets the request through, 401/403 blocks it.

⚠ Common pitfall: Needs `--with-http_auth_request_module` (built in on most distro packages). The auth endpoint should be `internal;` and return only a status, no body.

location /private/ {
    auth_request /auth;
    proxy_pass http://backend;
}

location = /auth {
    internal;
    proxy_pass http://auth-service/verify;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
}

Forward the request to an upstream backend. Can be a URL or an upstream name defined with `upstream { ... }`.

⚠ Common pitfall: Trailing slash matters: `proxy_pass http://backend/` rewrites the URI, `proxy_pass http://backend` keeps it. Get them mixed up and routing breaks silently.

location /api/ {
    proxy_pass http://127.0.0.1:3000/;
}

location / {
    proxy_pass http://backend;
}

Define a named pool of backend servers. Use the name with `proxy_pass http://<name>`.

upstream backend {
    server 127.0.0.1:3001;
    server 127.0.0.1:3002;
    keepalive 32;
}

upstream backend {
    least_conn;
    server app1.internal:8080 weight=3;
    server app2.internal:8080;
}

Forward the original Host header to the backend. Without this, your app sees the upstream name and routing/cookies break.

⚠ Common pitfall: After ANY `proxy_set_header` directive, the default headers (Host + Connection) are REPLACED — re-set Host explicitly when you customize headers.

proxy_set_header Host $host;

proxy_set_header Host $http_host;  # includes :port

Forward the real client IP. Without it the backend logs nginx as the client.

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 X-Forwarded-Host $host;

Use HTTP/1.1 to the upstream. Required for keep-alive AND for WebSocket upgrades.

⚠ Common pitfall: Default is HTTP/1.0 — without `proxy_http_version 1.1` upstream keep-alive does nothing and a fresh TCP connection is opened per request.

proxy_http_version 1.1;

proxy_http_version 1.1;
proxy_set_header Connection "";

Forward the Upgrade + Connection headers so an HTTP request becomes a WebSocket.

⚠ Common pitfall: Forget either header and the WS handshake just hangs at "Pending" in the browser DevTools network tab.

location /ws/ {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 3600s;
}

Max time between two read operations from the upstream (default 60s). Bump it for slow APIs or WebSockets.

⚠ Common pitfall: WebSockets idle 60s and the connection gets killed with a 504. Set to 3600s or higher for WS endpoints.

proxy_read_timeout 60s;

proxy_read_timeout 3600s;  # for WebSockets

How long nginx waits to establish the TCP connection to the upstream. Default 60s — usually too forgiving.

proxy_connect_timeout 5s;

proxy_connect_timeout 2s;
proxy_send_timeout 10s;
proxy_read_timeout 30s;

Buffer the upstream response before sending to the client. On = throughput. Off = streaming.

⚠ Common pitfall: For SSE (Server-Sent Events) or live log tailing, set `proxy_buffering off` or events queue up.

proxy_buffering on;

location /events {
    proxy_pass http://backend;
    proxy_buffering off;
    proxy_cache off;
}

Disable nginx rewriting Location / Refresh headers from the upstream. Use `default` to auto-rewrite based on proxy_pass.

proxy_redirect off;

proxy_redirect default;

Clear the Connection header so upstream keep-alive actually works. Required alongside proxy_http_version 1.1 for a pooled upstream.

⚠ Common pitfall: For a keep-alive upstream pool set Connection to "" (empty), NOT "keep-alive". For a WebSocket location set it to "upgrade" instead. Mixing these up breaks one or the other.

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

location /api/ {
    proxy_pass http://api;
    proxy_http_version 1.1;
    proxy_set_header Connection "";
}

Conditions under which nginx retries the request against the next upstream server. Lets a load balancer skip a dead backend.

⚠ Common pitfall: Do NOT include `non_idempotent` blindly — retrying a failed POST can double-charge or double-write. By default nginx already refuses to retry non-idempotent requests.

proxy_next_upstream error timeout http_502 http_503 http_504;
proxy_next_upstream_tries 2;
proxy_next_upstream_timeout 10s;

Define when to bypass the cache and go to the upstream (response may still be cached). Common: bypass on a "no-cache" hint.

proxy_cache_bypass $http_pragma $http_authorization;
proxy_no_cache $http_authorization;

Send SNI to an HTTPS upstream. Required when the backend serves multiple certs behind one IP and picks by SNI.

⚠ Common pitfall: Off by default — without it an HTTPS upstream on a shared host can return the wrong cert or reject the handshake. Set `proxy_ssl_name` if the SNI must differ from the proxy_pass host.

location / {
    proxy_pass https://backend.example.com;
    proxy_ssl_server_name on;
    proxy_ssl_protocols TLSv1.2 TLSv1.3;
}

Stop forwarding the client request headers to the upstream. Mostly used on auth subrequests to keep them lean.

location = /auth {
    internal;
    proxy_pass http://auth/verify;
    proxy_pass_request_body off;
    proxy_set_header Content-Length "";
}

Let nginx replace upstream error responses (≥300) with its own error_page handlers, so a backend 500 can show your branded page.

location / {
    proxy_pass http://backend;
    proxy_intercept_errors on;
    error_page 500 502 503 504 /50x.html;
}

root: nginx appends the URI to root. alias: nginx REPLACES the matched location with alias. Two different mechanics.

⚠ Common pitfall: For `/static/` → `/var/www/files/`, alias is right; root would look for `/var/www/files/static/...` and 404.

# root style — keeps URI prefix
location /static/ {
    root /var/www;  # serves /var/www/static/...
}

# alias style — strips URI prefix
location /static/ {
    alias /var/www/files/;  # serves /var/www/files/...
}

Try each path in order — first one that exists is served. The classic SPA fallback pattern.

⚠ Common pitfall: The LAST argument is either a URI (internal redirect) or `=code` (return status). A bare filename will be served literally — usually not what you want.

# SPA fallback
location / {
    try_files $uri $uri/ /index.html;
}

# 404 if nothing matches
location / {
    try_files $uri =404;
}

# PHP front controller
location / {
    try_files $uri $uri/ /index.php?$query_string;
}

Show a directory listing when no index file matches. Off by default — and that is correct for production.

⚠ Common pitfall: Turn this on globally and you leak file structure. Restrict to a specific location, or leave off.

location /downloads/ {
    autoindex on;
    autoindex_exact_size off;
    autoindex_localtime on;
}

Set the Expires + Cache-Control headers on responses. Standard for hashed asset files.

location ~* \.(js|css|woff2)$ {
    expires 1y;
    add_header Cache-Control "public, immutable";
}

expires -1;  # explicitly disable caching

Serve a custom page for a given status code. Use `=200` to also change the returned status, or a named location to proxy the handler.

⚠ Common pitfall: The custom 404 location should usually itself be `internal;` so it cannot be requested directly. Add `error_page 404 = /404.html;` (with `=`) to make it return 404, not 200.

error_page 404 /404.html;

error_page 500 502 503 504 /50x.html;
location = /50x.html { root /usr/share/nginx/html; internal; }

Stop browsers from MIME-sniffing a response away from its declared Content-Type. A one-line defense against some XSS vectors.

⚠ Common pitfall: A bare `add_header` inside a location is dropped the moment that location sets ANY other add_header. Use `always` and remember headers do not inherit into a child block that adds 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;

Send a CSP to control which sources of script, style, and media the browser will load. The strongest header-level XSS mitigation.

⚠ Common pitfall: Roll it out with `Content-Security-Policy-Report-Only` first and watch the violation reports — a too-strict CSP silently breaks your own site.

add_header Content-Security-Policy "default-src 'self'; img-src 'self' data:; object-src 'none'" always;

Serve a pre-compressed `file.gz` sitting next to the original instead of compressing on the fly. Zero CPU per request for static assets.

⚠ Common pitfall: You must generate the `.gz` files at build time (e.g. `gzip -k -9 dist/**/*.js`). nginx does not create them — it only serves them when they already exist.

location ~* \.(js|css|svg)$ {
    gzip_static on;
    expires 1y;
    add_header Cache-Control "public, immutable";
}

Cache open file descriptors, sizes, and existence checks. Big win for sites serving many small static files repeatedly.

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

Advertise byte-range support so clients can resume downloads and stream video with seeking. nginx enables ranges for static files automatically.

⚠ Common pitfall: Range support is disabled when gzip compresses the response on the fly — pre-compressed `gzip_static` files keep ranges working for large downloads.

location /video/ {
    root /var/media;
    add_header Accept-Ranges bytes;
    mp4;
}

Permanent redirect to HTTPS. Cleanest, fastest way — no rewrite engine, no regex.

⚠ Common pitfall: Use 301 (permanent) for production redirects so browsers + CDNs cache them. Use 302 only when the redirect target is genuinely temporary.

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

# Redirect old path
location = /old { return 301 /new; }

Rewrite a URI. `permanent` = 301, `redirect` = 302, `last` = re-search locations, `break` = stop rewriting.

⚠ Common pitfall: For a simple redirect prefer `return 301 ...` — it is faster and clearer than `rewrite`. Reach for rewrite only when you need regex captures.

rewrite ^/old/(.*)$ /new/$1 permanent;

rewrite ^/blog/(.*)\.html$ /posts/$1 last;

Conditional block. Officially "if is evil" — works inside `location` only and has surprising scope rules.

⚠ Common pitfall: Inside `if` blocks, only `return` and `rewrite ... last` are safe. Other directives can silently misbehave. Prefer a separate server block over `if`.

# Force HTTPS via if (only when a separate server block is awkward)
if ($scheme = "http") {
    return 301 https://$host$request_uri;
}

Tell crawlers a URL is gone for good (better than 404 for deleted pages).

location = /removed-feature { return 410; }

Temporary redirect. Browsers and CDNs do NOT cache it, so the move can be reverted. Use 307 to also preserve the request method/body.

⚠ Common pitfall: A 302 on a POST silently turns it into a GET in many clients. If you must redirect a POST and keep it a POST, use 307 instead.

location = /beta { return 302 /coming-soon; }

return 307 https://$host$request_uri;

Canonicalize the host so search engines index one URL. A dedicated server block for the www name is cleaner than an `if`.

⚠ Common pitfall: Pick ONE canonical host and stick with it everywhere (sitemap, canonical tag, redirect). Redirecting both ways creates a loop.

# www → root
server {
    listen 80;
    server_name www.example.com;
    return 301 $scheme://example.com$request_uri;
}

Drive hundreds of old-to-new redirects from a single `map`. Faster and far more readable than a wall of `if` or `location` rules.

⚠ Common pitfall: `map` blocks live in the `http {}` context, not inside `server` or `location`. The default value (the `default` line) is what unmatched URIs fall back to.

# in http { }
map $request_uri $redirect_to {
    default            "";
    /old-page          /new-page;
    /legacy/docs       /docs;
}

# in server { }
if ($redirect_to) {
    return 301 $redirect_to;
}

Path to the fullchain cert and private key. Required for any TLS listener.

⚠ Common pitfall: Use FULLCHAIN (cert + intermediates) not just the leaf cert — otherwise mobile clients and older browsers fail to verify.

ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem;
ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem;

Allowed TLS versions. TLS 1.0 / 1.1 are deprecated and broken in all modern browsers — never enable them.

ssl_protocols TLSv1.2 TLSv1.3;

Allowed cipher suites. Copy the latest "Modern" or "Intermediate" list from ssl-config.mozilla.org — do not invent your own.

ssl_protocols TLSv1.2 TLSv1.3;
ssl_prefer_server_ciphers off;
ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384;

Free TLS certs with auto-renew. `certbot --nginx` edits your nginx config in place. Renewal is via a systemd timer.

⚠ Common pitfall: Renewal needs port 80 reachable from the public internet. Behind a firewall use DNS-01 (`--manual --preferred-challenges dns`).

sudo certbot --nginx -d example.com -d www.example.com

sudo certbot renew --dry-run

sudo systemctl list-timers | grep certbot

HSTS — tells browsers to remember "use HTTPS only for this domain" for the given max-age.

⚠ Common pitfall: Once a browser receives HSTS with `includeSubDomains` + `preload`, you CANNOT downgrade for that period. Roll it out short max-age first (e.g. 1 day).

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

OCSP stapling — nginx fetches the OCSP response and attaches it to the handshake, saving the client a round-trip.

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

Shared TLS session cache across workers. 10MB ≈ 40,000 sessions. Big speed win on busy sites.

ssl_session_cache shared:SSL:10m;
ssl_session_timeout 1d;
ssl_session_tickets off;

Custom Diffie-Hellman params for DHE cipher suites. Generate a 2048-bit (or larger) file so you are not using nginx’s weak built-in default.

⚠ Common pitfall: Generating 4096-bit dhparam can take minutes and adds handshake cost for little real gain — 2048-bit is the common, well-supported choice. Pure TLS 1.3 / ECDHE setups do not use it at all.

openssl dhparam -out /etc/nginx/dhparam.pem 2048

ssl_dhparam /etc/nginx/dhparam.pem;

Enable TLS 1.3 0-RTT so a returning client can send the first request in the very first packet. Cuts a round-trip on reconnects.

⚠ Common pitfall: 0-RTT data is replayable by an attacker. Only allow it for idempotent requests, and check `$ssl_early_data` so you can refuse early-data POSTs at the app.

ssl_early_data on;
proxy_set_header Early-Data $ssl_early_data;

Trust store used to verify the OCSP responder and (with ssl_verify_client) client certs. Needed for stapling verification on some chains.

ssl_stapling on;
ssl_stapling_verify on;
ssl_trusted_certificate /etc/letsencrypt/live/example.com/chain.pem;

Require a client certificate (mutual TLS). nginx rejects the handshake unless the client presents a cert signed by `ssl_client_certificate`.

⚠ Common pitfall: Use `optional` instead of `on` if some paths are public — then gate the protected location on `$ssl_client_verify = SUCCESS` yourself.

ssl_client_certificate /etc/nginx/ca.crt;
ssl_verify_client on;
ssl_verify_depth 2;

if ($ssl_client_verify != SUCCESS) { return 403; }

The nginx ≥ 1.25.1 way to enable HTTP/2, separate from the listen line. Replaces the deprecated `listen ... http2` flag.

listen 443 ssl;
listen [::]:443 ssl;
http2 on;

Enable on-the-fly gzip compression for responses. Standard win for text content.

⚠ Common pitfall: Do NOT gzip already-compressed types (jpg, png, mp4, zip). Use `gzip_types` to explicitly list text MIME types.

gzip on;
gzip_vary on;
gzip_min_length 1024;
gzip_comp_level 5;
gzip_types text/plain text/css application/json application/javascript text/xml application/xml text/javascript;

Brotli compression (ngx_brotli module). ~15-25% smaller than gzip on text. Requires a module compiled in.

⚠ Common pitfall: `brotli` is NOT in stock nginx — `nginx -V | grep brotli` first. On Ubuntu use `libnginx-mod-brotli` or rebuild.

brotli on;
brotli_comp_level 5;
brotli_types text/plain text/css application/json application/javascript text/xml application/xml image/svg+xml;

Define an on-disk cache zone for upstream responses. Then enable per-location with `proxy_cache <zone>`.

proxy_cache_path /var/cache/nginx levels=1:2 keys_zone=mycache:10m max_size=1g inactive=60m use_temp_path=off;

location / {
    proxy_cache mycache;
    proxy_cache_valid 200 302 10m;
    proxy_cache_valid 404 1m;
    proxy_cache_use_stale error timeout updating http_500 http_502 http_503 http_504;
    add_header X-Cache-Status $upstream_cache_status;
    proxy_pass http://backend;
}

Cache directives for the BROWSER. `public, immutable` for hashed assets; `no-store` for HTML; `must-revalidate` for safe staleness.

add_header Cache-Control "public, max-age=31536000, immutable" always;

add_header Cache-Control "no-store" always;

Define exactly what makes two requests "the same" for the cache. The default ignores scheme; add it to avoid serving an http body for https.

⚠ Common pitfall: Leaving a per-user cookie or auth token out of the key is what lets one user’s private page get served to everyone. If responses vary by user, do not cache them.

proxy_cache_key "$scheme$request_method$host$request_uri";

When many requests miss the cache for the same key at once, let only one go to the upstream and make the rest wait for it. Stops a cache stampede.

proxy_cache_lock on;
proxy_cache_lock_timeout 5s;
proxy_cache_use_stale updating;

Only start caching a response after it has been requested this many times. Keeps one-hit URLs from filling the cache.

proxy_cache_min_uses 3;
proxy_cache_valid 200 10m;

Control whether nginx gzips responses that came from an upstream. Default `off` means proxied responses are never compressed — usually you want `any`.

⚠ Common pitfall: If gzip works for static files but not for proxied pages, this is almost always why — the default `gzip_proxied off` skips them.

gzip on;
gzip_proxied any;
gzip_vary on;

Expose whether each response was a HIT, MISS, BYPASS, EXPIRED, or STALE. The fastest way to confirm your cache config actually works.

add_header X-Cache-Status $upstream_cache_status always;

# then:
curl -sI https://example.com/ | grep -i x-cache-status

Define a per-IP request-rate zone. Then enforce it in a location with `limit_req zone=<name> burst=<n>`.

⚠ Common pitfall: Use `$binary_remote_addr` not `$remote_addr` — 4 bytes vs ~15 bytes, so the zone holds 4x more clients in the same memory.

# Define in http { }
limit_req_zone $binary_remote_addr zone=loginlimit:10m rate=5r/m;

# Apply in location
location /login {
    limit_req zone=loginlimit burst=10 nodelay;
    proxy_pass http://backend;
}

Define a per-IP concurrent-connection zone. Enforce with `limit_conn <name> <n>`.

limit_conn_zone $binary_remote_addr zone=perip:10m;

server {
    limit_conn perip 20;
}

HTTP status returned when the rate limit is exceeded. Default 503; 429 is the correct semantic.

limit_req_status 429;
limit_conn_status 429;

burst lets a short spike queue up beyond the rate; nodelay forwards those queued requests immediately instead of spacing them out. Together: smooth average, instant for bursts.

⚠ Common pitfall: Without `nodelay`, a `rate=10r/s burst=20` releases queued requests at one per 100ms, so a legit burst feels laggy. With `nodelay` they go through at once but the rate cap still holds over time.

limit_req_zone $binary_remote_addr zone=api:10m rate=10r/s;

location /api/ {
    limit_req zone=api burst=20 nodelay;
    proxy_pass http://backend;
}

Severity used when a request is delayed or rejected by a rate limit. Lower it to `notice` to stop limiter noise from dominating error.log.

limit_req_log_level notice;
limit_conn_log_level notice;

Cap the per-connection response bandwidth (bytes/s). Use `limit_rate_after` to send the first chunk fast, then throttle the rest of a large download.

location /downloads/ {
    limit_rate_after 10m;
    limit_rate 512k;
}

Exempt trusted IPs from rate limiting: a `geo` block sets a flag, a `map` turns the limiter key off for them so their requests never count.

geo $limit_exempt {
    default        0;
    10.0.0.0/8     1;
    192.168.0.0/16 1;
}
map $limit_exempt $limit_key {
    0 $binary_remote_addr;
    1 "";
}
limit_req_zone $limit_key zone=api:10m rate=10r/s;

Where + what to log per request. `main` is the default format name. Set to `off` for hot endpoints like /healthz.

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

access_log off;

access_log /var/log/nginx/api.log combined buffer=64k flush=5s;

Where + at what severity to log nginx-internal errors. Levels: debug, info, notice, warn, error, crit, alert, emerg.

⚠ Common pitfall: Setting `debug` floods the log. Use it only when actively debugging, with `error_log /tmp/debug.log debug;` so it does not hit the main log.

error_log /var/log/nginx/error.log warn;

error_log /var/log/nginx/error.log error;

Define a named log line format. Lots of useful variables: $request_time, $upstream_response_time, $body_bytes_sent.

log_format main '$remote_addr - $remote_user [$time_local] "$request" '
                '$status $body_bytes_sent "$http_referer" '
                '"$http_user_agent" "$http_x_forwarded_for" '
                'rt=$request_time urt=$upstream_response_time';

log_format json escape=json '{"time":"$time_iso8601","remote":"$remote_addr","req":"$request","status":$status,"rt":$request_time,"urt":"$upstream_response_time"}';

Follow the access log in real time. -F (capital) follows across log-rotate, which is what you actually want.

sudo tail -F /var/log/nginx/access.log

sudo tail -F /var/log/nginx/access.log | awk '{print $9}' | sort | uniq -c | sort -rn

Ship access logs straight to a syslog server (local or remote) instead of a file. Lets a log collector ingest nginx without tailing files.

access_log syslog:server=127.0.0.1:514,tag=nginx,severity=info main;

error_log syslog:server=logs.internal:514 warn;

Use a `map` on $request_uri or $http_user_agent to set a flag, then `access_log ... if=$flag` so probes and monitors never clutter the log.

map $request_uri $loggable {
    default        1;
    /healthz       0;
    /metrics       0;
}

access_log /var/log/nginx/access.log main if=$loggable;

Cache open log-file descriptors when you split logs across many files (e.g. per-vhost). Saves an open/close per request.

open_log_file_cache max=1000 inactive=20s valid=1m min_uses=2;

Turn the access log into a live HTML dashboard. GoAccess parses nginx’s combined/custom format and shows top URLs, status codes, and bandwidth.

⚠ Common pitfall: If you use a custom log_format, pass a matching `--log-format` to GoAccess or it parses nothing. The combined format works out of the box.

goaccess /var/log/nginx/access.log -o report.html --log-format=COMBINED --real-time-html

zcat /var/log/nginx/access.log.*.gz | goaccess --log-format=COMBINED -o report.html

nginx connected to the upstream but got an invalid / empty / closed response. Almost always the BACKEND is dead, crashed, or wrong port.

⚠ Common pitfall: Check the backend is alive first: `curl http://127.0.0.1:3000`. Then nginx error.log — you usually see "connect() failed" or "upstream prematurely closed connection".

curl -v http://127.0.0.1:3000

sudo tail -f /var/log/nginx/error.log

sudo journalctl -u my-backend -n 200

Upstream is alive but did not answer within proxy_read_timeout. Either bump the timeout or fix the slow query.

⚠ Common pitfall: WebSockets and long-poll endpoints constantly hit this. Set `proxy_read_timeout 3600s` only on those specific locations, not globally.

proxy_read_timeout 3600s;

proxy_send_timeout 600s;

TLS negotiation failed. Most common causes: wrong cert/key pair, missing intermediates, unsupported protocol or cipher, SNI mismatch.

⚠ Common pitfall: Always test with `openssl s_client -connect host:443 -servername host` (the -servername sends SNI). Browsers cache TLS failures for a long time.

openssl s_client -connect example.com:443 -servername example.com

openssl x509 -in fullchain.pem -noout -dates -subject -issuer

sudo nginx -t

Worker user cannot read your files. Check ownership against the `user` directive AND that every parent directory is `x`-able.

⚠ Common pitfall: Every parent directory needs the `x` bit for nginx, not just the file with `r`. `chmod -R 755 /var/www/site` fixes it in one shot.

ls -ld /var/www /var/www/site /var/www/site/index.html

sudo chown -R www-data:www-data /var/www/site

sudo chmod -R 755 /var/www/site

Another process holds the port. Apache, an old nginx, a stray docker container — find it and stop it.

sudo ss -tlnp | grep -E ":80|:443"

sudo lsof -i :80 -i :443

sudo systemctl stop apache2

Two server blocks declare the same server_name on the same listen. nginx picks ONE silently — your other site goes dark.

⚠ Common pitfall: Run `nginx -T | grep -E "(server_name|listen)"` after every deploy to spot duplicates before they bite.

sudo nginx -T 2>&1 | grep -E "server_name|listen" | sort | uniq -d

You hit worker_connections × worker_processes. Bump worker_connections AND worker_rlimit_nofile AND systemd LimitNOFILE.

worker_rlimit_nofile 65535;
events { worker_connections 16384; }

# /etc/systemd/system/nginx.service.d/override.conf
[Service]
LimitNOFILE=65535

Uploads larger than `client_max_body_size` get 413. Set it on the http, server, or location level.

# In http or server
client_max_body_size 100m;

# Only the upload endpoint
location /upload {
    client_max_body_size 1g;
    proxy_pass http://backend;
}

The upstream response headers overflow nginx’s proxy buffers, giving a 502. Common with big Set-Cookie or auth headers.

⚠ Common pitfall: Raise `proxy_buffer_size` (the buffer for the response header) AND `proxy_buffers`. The header alone is limited by proxy_buffer_size, not the whole proxy_buffers pool.

proxy_buffer_size 16k;
proxy_buffers 8 16k;
proxy_busy_buffers_size 32k;

try_files or rewrite keeps pointing back at a URI that re-enters the same location, and nginx aborts the loop with a 500.

⚠ Common pitfall: Classic cause: `try_files $uri $uri/ /index.php` inside `location ~ \.php$` — the fallback re-matches the php location forever. Move the fallback to `location /`.

sudo tail -f /var/log/nginx/error.log | grep "rewrite or internal redirection cycle"

Every server in the upstream pool is marked down (too many failed health checks), so nginx returns 502 with "no live upstreams" in error.log.

⚠ Common pitfall: Aggressive `max_fails` plus a brief backend blip can take the whole pool down at once. Tune `max_fails` / `fail_timeout`, and keep a `backup` server.

upstream app {
    server a:8080 max_fails=3 fail_timeout=15s;
    server b:8080 max_fails=3 fail_timeout=15s;
    server c:8080 backup;
}

Two server blocks both claim `default_server` on the same listen address, so `nginx -t` refuses to load the config.

⚠ Common pitfall: Search all included files: `grep -rn default_server /etc/nginx/`. A leftover `00-default.conf` is the usual culprit.

sudo grep -rn "default_server" /etc/nginx/

sudo nginx -t

Your HTTP→HTTPS redirect fires forever because the CDN talks to nginx over HTTP, so $scheme is always "http" even on a real HTTPS request.

⚠ Common pitfall: Redirect on `$http_x_forwarded_proto` instead of `$scheme`, or set `proxy_protocol`/realip so nginx knows the original scheme. Never trust $scheme behind an offloading proxy.

if ($http_x_forwarded_proto = "http") {
    return 301 https://$host$request_uri;
}

nginx logs "socket() failed (24: Too many open files)" because the file-descriptor limit is too low for the connection volume.

⚠ Common pitfall: Raise THREE things together: `worker_rlimit_nofile`, systemd `LimitNOFILE`, and the OS `nofile` ulimit. Missing any one and the real ceiling is the lowest of them.

worker_rlimit_nofile 100000;

# /etc/systemd/system/nginx.service.d/limits.conf
[Service]
LimitNOFILE=100000

cat /proc/$(pgrep -o nginx)/limits | grep "open files"

Headers set with add_header at the server level vanish inside any location that adds its OWN add_header. nginx replaces, it does not merge.

⚠ Common pitfall: Re-declare every header you need in each location that touches headers, or centralize them with the headers-more module’s `more_set_headers`, which does inherit.

# server-level header is dropped here:
location /api/ {
    add_header X-Api "1" always;          # this replaces ALL inherited add_headers
    add_header X-Frame-Options SAMEORIGIN always;  # must repeat
}

Bare-bones static site server block. Serves /var/www/site, gzip on, long-cache hashed assets, SPA-friendly fallback.

server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    root /var/www/site;
    index index.html;

    gzip on;
    gzip_types text/plain text/css application/json application/javascript image/svg+xml;

    location ~* \.(js|css|woff2|png|jpg|svg)$ {
        expires 1y;
        add_header Cache-Control "public, immutable";
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Forward / to a Node app on 127.0.0.1:3000 with the standard forwarded headers and WebSocket support.

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

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://node_app;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        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;
        proxy_buffering on;
    }
}

Full HTTPS server with HTTP→HTTPS redirect, modern TLS, HSTS, OCSP stapling. Drop-in template.

# HTTP → HTTPS
server {
    listen 80;
    listen [::]:80;
    server_name example.com www.example.com;
    return 301 https://$host$request_uri;
}

# HTTPS
server {
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name example.com www.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;
    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; includeSubDomains" always;

    root /var/www/site;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Round-robin (default) or least-conn load balance across three backends, with health-aware fail_timeout.

upstream backend {
    least_conn;
    server app1.internal:8080 max_fails=3 fail_timeout=30s;
    server app2.internal:8080 max_fails=3 fail_timeout=30s;
    server app3.internal:8080 max_fails=3 fail_timeout=30s backup;
    keepalive 64;
}

server {
    listen 80;
    server_name api.example.com;

    location / {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_next_upstream error timeout http_502 http_503 http_504;
    }
}

Pass .php files to PHP-FPM via a unix socket. Standard WordPress / Laravel-ready front controller.

server {
    listen 80;
    server_name example.com;
    root /var/www/site/public;
    index index.php index.html;

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    location ~ /\.ht { deny all; }
}

Cheap exact-match health endpoint with no logging. Friendly to load balancers, Kubernetes probes, uptime monitors.

server {
    listen 80 default_server;

    location = /healthz {
        access_log off;
        return 200 "ok\n";
        add_header Content-Type text/plain;
    }
}

Serve a friendly "be right back" page with HTTP 503 and a Retry-After header. Flip a single file to toggle maintenance mode on or off.

server {
    listen 80;
    server_name example.com;
    root /var/www/site;

    # If the flag file exists, everything returns the maintenance page.
    if (-f $document_root/maintenance.on) {
        return 503;
    }

    error_page 503 @maintenance;
    location @maintenance {
        root /var/www/site;
        rewrite ^(.*)$ /maintenance.html break;
        add_header Retry-After 3600 always;
    }

    location / {
        try_files $uri $uri/ /index.html;
    }
}

Answer OPTIONS preflight requests at nginx and add CORS headers to API responses, so a browser front-end on another origin can call the API.

server {
    listen 80;
    server_name api.example.com;

    location /api/ {
        if ($request_method = OPTIONS) {
            add_header Access-Control-Allow-Origin "https://app.example.com" always;
            add_header Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS" always;
            add_header Access-Control-Allow-Headers "Authorization, Content-Type" always;
            add_header Access-Control-Max-Age 86400 always;
            add_header Content-Length 0;
            return 204;
        }

        add_header Access-Control-Allow-Origin "https://app.example.com" always;
        proxy_pass http://backend;
    }
}

Reverse-proxy gRPC over HTTP/2 with grpc_pass. nginx terminates TLS for the client and forwards to a plaintext or TLS gRPC backend.

⚠ Common pitfall: gRPC needs HTTP/2 end to end. Use `grpc_pass` (not proxy_pass) and `grpc_pass grpcs://` for a TLS backend. The listen side must have `http2 on;`.

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

    ssl_certificate     /etc/letsencrypt/live/grpc.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/grpc.example.com/privkey.pem;

    location / {
        grpc_pass grpc://127.0.0.1:50051;
        grpc_set_header Host $host;
    }
}

Cache dynamic HTML for just 1 second. Under a traffic spike this collapses thousands of identical requests into one upstream hit, with stale-while-revalidate.

⚠ Common pitfall: Never micro-cache responses that vary per logged-in user. Add `proxy_cache_bypass`/`proxy_no_cache` on the auth cookie so authenticated requests skip the shared cache.

proxy_cache_path /var/cache/nginx/micro levels=1:2 keys_zone=micro:10m max_size=256m inactive=60s use_temp_path=off;

map $http_cookie $no_cache {
    default       0;
    ~session_id   1;
}

server {
    location / {
        proxy_cache micro;
        proxy_cache_valid 200 1s;
        proxy_cache_use_stale updating error timeout;
        proxy_cache_lock on;
        proxy_cache_bypass $no_cache;
        proxy_no_cache $no_cache;
        add_header X-Cache-Status $upstream_cache_status always;
        proxy_pass http://backend;
    }
}

Map each subdomain to its own document root automatically with a captured server_name and a variable in root. Add one folder, get one site.

⚠ Common pitfall: Wildcard server blocks need a wildcard DNS record (`*.example.com`) and, for HTTPS, a wildcard TLS cert. Validate the captured `$sub` if you do not trust arbitrary subdomains.

server {
    listen 80;
    server_name ~^(?<sub>[a-z0-9-]+)\.example\.com$;
    root /var/www/tenants/$sub;
    index index.html;

    location / {
        try_files $uri $uri/ /index.html;
    }
}