Nginx Cheatsheet

Reverse Proxy

Use this Nginx reference while you build software engineering projects, review code, or refresh the syntax you reach for most.

Minimal Reverse Proxy

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

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

If proxy_pass URL has a trailing slash (http://backend/), Nginx strips the location prefix before forwarding.

Essential proxy_pass Variants

# Proxy to localhost port
proxy_pass http://127.0.0.1:3000;

# Proxy to upstream group (defined separately)
proxy_pass http://myapp;

# Proxy to Unix socket
proxy_pass http://unix:/run/app.sock:;

# Strip location prefix (trailing slash on both)
location /api/ {
    proxy_pass http://127.0.0.1:4000/;   # /api/users → /users
}

# Preserve location prefix (no trailing slash)
location /api/ {
    proxy_pass http://127.0.0.1:4000;    # /api/users → /api/users
}

Headers to Always Set

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

    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;
}

Put these in a shared snippet (/etc/nginx/snippets/proxy-headers.conf) and include it.

Full Recommended Proxy Block

location / {
    proxy_pass http://backend;

    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_http_version 1.1;
    proxy_set_header Connection "";      # Required for keepalives with upstream

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

    proxy_buffering        on;
    proxy_buffers          8 16k;
    proxy_buffer_size      16k;
}

Timeout Directives

Directive	Default	What it covers
`proxy_connect_timeout`	60s	Time to establish connection to upstream
`proxy_send_timeout`	60s	Time between successive sends to upstream
`proxy_read_timeout`	60s	Time between successive reads from upstream

Buffering

Directive	Recommended	Effect
`proxy_buffering on`	on	Buffer upstream response in memory/disk
`proxy_buffers 8 16k`	—	Number and size of per-request buffers
`proxy_buffer_size 16k`	—	Buffer for the first part of the response (headers)
`proxy_max_temp_file_size 0`	—	Disable temp file overflow

Turn buffering off for streaming / SSE / WebSocket responses:

proxy_buffering off;

WebSocket Proxying

location /ws/ {
    proxy_pass http://ws_backend;

    proxy_http_version 1.1;
    proxy_set_header Upgrade    $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 3600s;   # Keep long-lived connections alive
}

Proxy Cache (Basic)

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

    server {
        location / {
            proxy_pass http://backend;
            proxy_cache my_cache;
            proxy_cache_valid 200 302  10m;
            proxy_cache_valid 404       1m;
            add_header X-Cache-Status $upstream_cache_status;
        }
    }
}

Hiding Upstream Info

proxy_hide_header X-Powered-By;   # Drop leaky upstream headers
server_tokens off;                # Server: nginx (no version)
more_clear_headers Server;        # Remove Server entirely (headers-more module)

Nginx always replaces the upstream Server header with its own, so proxy_hide_header Server does nothing — use server_tokens off to hide the version, or headers-more to strip the header.

Passing Request Body

client_max_body_size 50m;       # Max upload size (default 1m)
client_body_buffer_size 128k;   # Buffer before writing to disk
proxy_request_buffering on;     # Buffer full request before sending upstream