NGINX Reverse-Proxy vhost Design Prompt
Generate a clean, production-ready reverse-proxy server block for your backend app — correct headers, timeouts, keepalive, and WebSocket support — instead of copy-pasting a Stack Overflow snippet that leaks the client IP.
- Target user
- Engineers standing up a new NGINX vhost in front of an app server or container
- Difficulty
- Intermediate
- Tools
- Claude, ChatGPT, Cursor
The prompt
You are a senior infrastructure engineer who writes NGINX reverse-proxy configs that survive production. You set forwarding headers correctly, never break WebSockets, and you comment every non-obvious directive.
I will provide:
- The public hostname(s) this vhost serves: [DESCRIBE HOSTNAMES]
- The backend address (host:port, unix socket, or container): [DESCRIBE BACKEND]
- Whether the app uses WebSockets / SSE / long polling: [YES/NO + DETAILS]
- TLS setup (terminating here, behind another LB, or plain HTTP for now): [DESCRIBE TLS]
- Any static assets NGINX should serve directly: [DESCRIBE STATIC PATHS]
Build the config:
1. **Server block skeleton** — `listen`, `server_name`, and a separate `upstream {}` block (named, not an inline `proxy_pass` to a literal host) so the backend is reusable and tunable.
2. **Upstream tuning** — add `keepalive` to the upstream and set `proxy_http_version 1.1` plus `proxy_set_header Connection ""` so connections are reused, not torn down per request.
3. **Forwarding headers** — `Host`, `X-Real-IP`, `X-Forwarded-For`, `X-Forwarded-Proto`. Explain why each matters and what breaks (redirect loops, wrong client IP in logs) if it is missing.
4. **WebSocket / upgrade** — if needed, the `Upgrade`/`Connection` map and `proxy_set_header` lines, in their own `location` if the app isolates WS to a path.
5. **Static + proxy split** — `try_files` or a `location` for static assets so NGINX serves them without round-tripping the app; proxy everything else.
6. **Timeouts and buffers** — sensible `proxy_connect_timeout`, `proxy_read_timeout`, and a note on `proxy_buffering` for streaming responses.
Output: (a) the complete, commented `upstream {}` + `server {}` config as one block, (b) a short table of every header you set and why, (c) the `nginx -t` command and a `curl -H "Host: ..."` smoke test. Treat the config as a reviewable artifact: validate with `nginx -t` and reload — never paste directives straight into a live prod file.
Run this prompt with AI
Test it, get an AI-improved version, or compare models — live in the Prompt Workspace. No copy-paste.
Why this prompt works
Most broken reverse proxies fail in the same three places: missing forwarding headers (so the backend sees NGINX’s IP, not the client’s), no keepalive on the upstream (so every request opens a fresh TCP connection), and a WebSocket upgrade that silently downgrades to HTTP. The prompt makes each of these an explicit, numbered requirement so none gets skipped.
Forcing a named upstream {} block instead of an inline proxy_pass http://host:port produces a config you can later add load balancing, health checks, and keepalive to without restructuring. It is the difference between a throwaway snippet and a maintainable building block.
The header-explanation table and the curl -H "Host: ..." smoke test keep you in control: you understand every directive before it ships, and you prove the vhost routes correctly behind nginx -t rather than discovering a redirect loop in production.
Related prompts
-
NGINX 502/504 Bad Gateway Triage Prompt
Turn a wall of error.log lines plus your upstream config into a ranked root-cause list and a concrete fix for 502/504 errors — without guessing or restarting blindly.
-
NGINX CORS & Preflight Proxy Prompt
Get correct, secure CORS handling in NGINX for a reverse-proxied API — OPTIONS preflight, Access-Control-* headers, credentials, and per-origin allow-listing — without the classic duplicate-header and wildcard-with-credentials footguns.
-
NGINX auth_request Subrequest SSO Prompt
Design a correct `auth_request` gateway that offloads authentication to an external SSO/auth service — forwarding the right headers, handling 401/403 vs 5xx distinctly, and passing identity back to your app — instead of a fragile snippet that leaks unauthenticated traffic on the auth service's bad day.
-
NGINX HTTP/3 (QUIC) Reverse-Proxy Setup Prompt
Generate a correct, production-ready HTTP/3 + QUIC server block for an existing NGINX reverse proxy — UDP 443 listeners, Alt-Svc advertisement, congestion/retry settings, and TLS 1.3 — without breaking your working HTTP/2 fallback.
More NGINX prompts & error guides
Browse every NGINX prompt and troubleshooting guide in one place.
Reading prompts? Get all 500 in one free PDF
500 battle-tested, copy-paste AI prompts engineered by a senior systems engineer — every one with fill-in placeholders and safety/back-out notes. Drop your email and it's yours.
- 500 prompts: Linux · Kubernetes · Terraform · OpenStack · GitLab · Docker · Monitoring · Incident Response
- Instant PDF download — yours free, forever
- Plus one practical AI-workflow email a week (no spam)
Single opt-in · unsubscribe anytime · no spam.