nginx

Deep, practical guidance for writing, configuring, reviewing, and debugging nginx — a full-spectrum nginx assistant, not just an incident-response tool. Use it for routine setup (new vhost, reverse proxy, TLS, caching, security) just as much as for hard problems. On top of standard best practices it encodes hard-won operational lessons (mobile/MTU black holes, DPI filtering, add_header inheritance traps, HTTP/2 syntax drift across versions) so answers are correct and version-aware instead of generic snippets.

What this skill helps with

Authoring & setup (the everyday case):

• Stand up a new site / virtual host from scratch (HTTP→HTTPS, certs, HTTP/2).
• Reverse proxy to an app: correct headers, WebSockets, timeouts, keep-alive.
• Frontends (SPA / Next.js / React), object storage (S3/MinIO), APIs.
• Load balancing and upstream pools.
• Caching (static + proxy cache), gzip/brotli compression.
• TLS/SSL setup and tuning, HTTP/3, OCSP stapling, redirects.
• Security hardening: headers, rate limiting, real-IP behind a CDN, allow/deny.

Review & refactor:

• Audit an existing .conf against the checklist below; clean up cruft.

Debug (when something's wrong):

• "Won't load", slow on mobile, VPN asymmetry, 502/504/413, redirect loops,

cert/SNI errors — diagnosed from logs, not guesswork.

How to use this skill

1. Identify the task type and jump to the matching reference. For **setup/

authoring, produce a complete, correct config from the patterns in the references (adapted to the user's stack), then validate it. For debugging**, diagnose from logs first, then make the minimal correct change — don't paste a generic config at a problem you haven't localized.

1. Always preserve a path to rollback. Before editing a production .conf,

note the original. Never touch ssl_certificate* lines unless explicitly asked.

1. Validate before declaring done. Every change must pass nginx -t. Tell

the user to run nginx -t && systemctl reload nginx (reload, not restart — reload is zero-downtime).

1. Be version-aware. Several directives changed syntax across nginx

releases (see Anti-patterns → "HTTP/2 syntax"). When unsure, ask for nginx -v or use the backward-compatible form.

Decision tree — pick the right reference

Core review checklist (apply to any .conf you touch)

Run through this whenever you review or write a config:

• `nginx -t` clean? Syntax + duplicate server_name + missing files.
• HTTP/2 enabled on listen 443? Use the version-correct syntax.
• Reverse proxy headers present: Host, X-Real-IP, X-Forwarded-For,

X-Forwarded-Proto? Is X-Forwarded-Proto the real scheme (https, not a hardcoded http)?

• WebSocket endpoints have proxy_http_version 1.1 + Upgrade +

Connection upgrade map?

• `add_header` inheritance: does any location re-declare add_header and

thereby silently drop security/CORS headers from the parent? (See anti-patterns — this is the #1 silent bug.)

• No `add_header Last-Modified $date_gmt` or similar cache-busting hacks

that force clients to re-download everything (kills mobile).

• No duplicate `server` blocks / conflicting server_name.
• `if` used only for safe things (return/rewrite ... last), never to

wrap proxy_pass or add_header (see "if is evil").

• `client_max_body_size` set appropriately for upload endpoints (default

1m causes 413 on file uploads).

• TLS session reuse configured (directly or via certbot's

options-ssl-nginx.conf) so mobile clients don't renegotiate per request.

• Redirects: single clean return 301 https://$host$request_uri; — not a

pile of certbot if blocks.

Golden rules

• Diagnose from logs, not vibes. "Seems better" is not a fix. For

connectivity/loading complaints, the access log keyed by the user's IP tells you whether the request even arrived. See references/diagnostics.md.

• Reload, don't restart. systemctl reload nginx re-reads config with no

dropped connections. Restart only when changing worker_* or modules.

• One concern per change. When debugging, change one thing, re-test, keep

or revert. Don't stack five "fixes" — that's how the bad configs in the wild got their cargo-cult cruft.

• Reproduce the cert layout, never invent it. If certs are `# managed by

Certbot`, leave those lines alone; certbot rewrites them on renewal.

• Prefer `map` over `if`. Most if use cases are better as map at

http level.

Provided scripts

• scripts/nginx-check.sh — runs nginx -t, prints version, lists every

server_name/listen pair to spot duplicates and conflicts, and flags common anti-patterns (literal X-Forwarded-Proto http, Last-Modified $date_gmt, missing http2, if wrapping risky directives). Read-only.

• scripts/diagnose-ip.sh <IP> [access_log] — classifies a connectivity

complaint by grepping the access log for one client IP: requests arriving but large responses truncating → server/MTU layer; total silence → path/DPI problem upstream of nginx. Implements the workflow in diagnostics.md.

Run scripts with the config or log path as argument; they make no changes.