nginx Config Generator — HTTP/3, WebSocket, Security

What does the nginx config generator do?

The generator is an editor for nginx server blocks. You pick one of eight block types (static hosting, SPA fallback, reverse proxy, PHP-FPM, load balancer, redirect-only, TCP stream, UDP stream), tune fields like server_name, root and upstream, and the generator assembles every directive in the correct order. Optionally, you can paste an existing .htaccess — the generator translates redirects, rewrites, headers and ErrorDocuments into nginx directives automatically. Everything happens in the browser. No upload, no account, no cookie banner.

Six presets cover the most common stack combinations:

• SPA — static hosting — Single-page app with an Astro/SvelteKit/Vite build, long-cache for hashed assets, fallback to index.html, HTTP/3 on.
• Node.js — reverse proxy — Node/Bun server behind nginx with WebSocket upgrade wired correctly.
• Python — Uvicorn/ASGI — FastAPI or Starlette via Uvicorn, rate-limit “API”.
• WordPress — PHP-FPM — PHP-FPM via Unix socket, wp-config.php and .env denied.
• Strict HTTPS — A-grade audit — tuned for Mozilla Observatory A, TLS 1.3, COOP/COEP/CORP.
• Load balancer — least_conn — nginx in front of three backend nodes, health failover via max_fails.

Which server-block types are built in?

Eight block types, grouped by use case:

• Static hosting — try_files $uri $uri/ =404;. Classic for Hugo, 11ty, plain HTML.
• SPA fallback — try_files $uri $uri/ /index.html; plus long-cache for hashed assets. Default for any client-side routing app.
• Reverse proxy — proxy_pass to an upstream URL, with every standard X-Forwarded-* header. Optional WebSocket upgrade.
• PHP-FPM — fastcgi_pass to a Unix socket, with try_files permalinks and deny rules for wp-config.php, .env, .git.
• Load balancer — proxy_pass http://backend_pool; plus the matching upstream block template (commented because upstream {} lives outside server {}).
• Redirect-only — return 301 https://www.example.com$request_uri;. For www-canonical and domain migrations.
• TCP stream — for stream {} scope, e.g. Postgres/Redis proxying. The block notes the scope switch.
• UDP stream — analogous for DNS or QUIC forwarding.

How does the HTTP/3 + QUIC support work?

HTTP/3 supersedes HTTP/2 and uses QUIC instead of TCP. QUIC is UDP-based, folds TLS into the connection setup and eliminates HTTP/2’s head-of-line blocking. nginx has shipped QUIC in its official build since version 1.25 (previously only in the nginx-quic branch). The generator emits four directives the moment you enable HTTP/3:

listen 443 quic reuseport;
listen [::]:443 quic reuseport;
http3 on;
ssl_early_data on;
add_header Alt-Svc 'h3=":443"; ma=86400' always;

The Alt-Svc header signals to browsers that HTTP/3 is available on port 443; ma=86400 caches that hint for 24 hours. Browsers that do not yet speak HTTP/3 ignore the header and stay on HTTP/2.

What makes WebSocket upgrade correct?

WebSocket reverse-proxying breaks in most naive nginx configs because the connection upgrade is missing. The correct pattern consists of four parts:

1. map directive at http {} scope — translates the client’s Upgrade header into a matching Connection value:

   map $http_upgrade $connection_upgrade {
     default upgrade;
     ''      close;
   }

2. proxy_set_header Upgrade $http_upgrade; — forwards the upgrade signal to the backend.
3. proxy_set_header Connection $connection_upgrade; — overrides nginx’s default Connection: close on reverse-proxied requests.
4. proxy_read_timeout 86400s; — sets the read timeout to 24 hours so idle WebSockets are not dropped after the 60-second default.

The generator wires all four automatically as soon as you tick the WebSocket checkbox on a reverse- proxy or load-balancer block. This is the most common pain point in WebSocket setups — and the main reason for “why does my connection keep dropping” threads in forums.

Which security headers are emitted?

Six headers belong in every modern nginx block (see Mozilla Web Security Guidelines):

• Strict-Transport-Security — HSTS with max-age=31536000; includeSubDomains; preload. Preload is on by default; a toggle lets you disable it for subdomains that still need HTTP fallbacks.
• Content-Security-Policy — Starter value with default-src 'self', frame-ancestors 'none'. Toggle for report-only mode during rollout.
• Permissions-Policy — Everything off by default (camera=(), microphone=(), geolocation=(), payment=(), usb=(), interest-cohort=(), browsing-topics=()).
• Cross-Origin-Opener-Policy — same-origin against window.opener tampering.
• Cross-Origin-Embedder-Policy — Optional require-corp for SharedArrayBuffer use cases.
• Cross-Origin-Resource-Policy — same-origin blocks cross-origin embeds of your own assets.

Every header carries the always flag. Without always nginx drops headers on 4xx/5xx responses — which many audit tools (Mozilla Observatory, securityheaders.com) count as an A-level violation. Before deploying, validate the CSP at the external CSP Evaluator.

How does the rate-limit profile work?

nginx rate limiting combines two directives:

• limit_req_zone at http {} scope — reserves shared memory and defines the rate.
• limit_req zone=<name> burst=<n> nodelay; inside the location block — references the zone.

Common bug in public generators: the zone is emitted, but the location reference is missing — the zone stays orphaned (see the open issue in the most popular online generator). The generator emits both together and injects the reference into the first location block of the server block. Three profiles:

• Gentle — 30 r/s, burst 50, limit_conn 100. For normal websites with real user traffic.
• API — 10 r/s, burst 20, limit_conn 50. For REST/GraphQL APIs with token-based throttling.
• Strict — 5 r/s, burst 10, limit_conn 20. For login endpoints, webhook receivers, critical routes.

burst defines how many requests beyond the rate are accepted before 429 responses fire. nodelay means: burst requests are processed immediately, not buffered against the rate. Without nodelay, nginx would artificially delay a burst request, which is rarely the desired behaviour in practice.

What does the .htaccess to nginx converter do?

Apache and nginx have different configuration models: Apache reads .htaccess per request (costs performance, gives flexibility), nginx parses its configuration once at reload (faster, no per-request override). A full 1:1 conversion does not exist, but the important directives map:

Apache	nginx
Redirect 301 /old /new	rewrite ^/old$ /new permanent;
Redirect 302 /a /b	rewrite ^/a$ /b redirect;
RewriteRule ^foo$ /bar [L]	rewrite ^foo$ /bar last;
RewriteRule … [R=301,L]	rewrite … permanent;
Header always set X-Frame-Options DENY	add_header X-Frame-Options "DENY" always;
ErrorDocument 404 /404.html	error_page 404 /404.html;
Options -Indexes	autoindex off;
Require ip 192.168.1.1	allow 192.168.1.1;
Deny from 203.0.113.4	deny 203.0.113.4;
<IfModule>	flattened with comment (nginx has no module-conditional)

Non-mappable directives come back as # TODO (could not convert): … comments. The converter is deterministic — same input, same output, no AI rate limit, no cloud round-trip. The instructions banner at the top (“paste inside your nginx server { ... } block”) is mandatory reading: the emitted directives belong in the right scope.

Which pain points does this generator help me avoid?

Four classics that show up in nginx tutorials over and over — and that the generator avoids:

1. WebSocket dropping after 60 seconds — the usual cause is missing proxy_read_timeout 86400s; plus the incorrect upgrade headers. The generator wires both automatically.
2. Rate-limit zone without reference — the limit_req_zone gets emitted, but limit_req in the location block is missing. Effect: zero. The generator emits both together.
3. Security headers disappearing on error pages — without always nginx drops headers on 4xx/5xx responses. The generator sets always on every add_header.
4. HTTP/3 misconfigured — missing reuseport, missing ssl_early_data, no Alt-Svc header. The generator emits all four directives the moment HTTP/3 is on.

How is privacy handled?

Pure-client. The generator runs entirely in the browser. There is no server endpoint for config validation, no telemetry call, no cookie, no account. Close the tab and your settings are gone — the generator does not persist anything. If you want a history, download the nginx.conf after each edit and version it in your repo.

What is intentionally not built?

• No live nginx -t validation — would require a server round-trip or a WebAssembly port of nginx itself. Instead, the generator header and the UI hint point to sudo nginx -t after deploy.
• No automatic Let’s Encrypt issuance — the generator only emits the Certbot webroot snippet. Activating the certificate needs server access and is outside the browser scope.
• No Nginx Proxy Manager GUI mode — if you want a GUI-first workflow, use Nginx Proxy Manager directly. This generator is for devs who keep configuration as code.
• No ngx_mod_security rules — WAF tuning is a separate tool (too specialised, too ruleset- specific).
• No Apache 2.2 variant — .htaccess 2.2 is covered by the sibling tool htaccess-generator.
• No caching-profile editor — the emitted gzip defaults and the long-cache rule in the SPA block are enough for the 90 % use case.

Where can I dig deeper?

• nginx documentation — official directives reference
• nginx on Wikipedia — history, architecture, deployments
• Mozilla SSL Configuration Generator — TLS profile reference
• hstspreload.org — submission list for HSTS preload domains
• CSP Evaluator — external validator for Content-Security-Policy
• RFC 9114 (HTTP/3) — HTTP/3 specification
• Cloudflare Learning Center — WebSocket — WebSocket protocol fundamentals