Nginx WebSocket Proxy Generator

Generate an nginx config for proxying WebSocket connections with Upgrade and Connection headers and long read timeouts

Websocket Proxy modepreset

Forward `Upgrade` + `Connection` headers and disable buffering for long-lived sockets.

Switch mode:

Server

server_name

HTTP portEnable HTTPS listen

Websocket

Upgrade locationWebsocket upstreamIdle timeout (s)Optional fallback proxy_pass

Common

Gzip compressionSecurity headers (X-Content-Type, Frame-Options, Referrer-Policy)

access_logerror_log

Custom add_header lines

nginx.conf preview

Drop into /etc/nginx/conf.d/ or/etc/nginx/sites-available/.

# Maps the Connection header to 'upgrade' iff the client requested a websocket.
map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}

server {
  listen 80;
  listen [::]:80;
  server_name example.com;

  # Recommended security headers
  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;

  # Compression
  gzip            on;
  gzip_vary       on;
  gzip_min_length 1024;
  gzip_proxied    any;
  gzip_comp_level 5;
  gzip_types      text/plain text/css application/json application/javascript application/xml+rss application/atom+xml image/svg+xml;

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

  location /ws {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header   Upgrade $http_upgrade;
    proxy_set_header   Connection $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_buffering off;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
  }
}

Validate before reloading

sudo nginx -t && sudo systemctl reload nginx

Heads up

Replace `example.com` with your real hostname before deploying.

Loading tool...

What is Nginx WebSocket Proxy Generator

Written by Giorgos Kostas. Last reviewed: April 18, 2026

Nginx WebSocket Proxy Generator emits the canonical websocket-aware proxy block — including the `map $http_upgrade $connection_upgrade` directive that Nginx's docs require.

It tunes the parts that trip up websocket setups: `proxy_http_version 1.1`, `proxy_buffering off`, and a configurable `proxy_read_timeout` for long-idle sockets.

Why use it

Get the `map` block right the first time — websockets break silently when `Connection` isn't set to the upgraded value.
Stop sockets from being killed by the default 60s `proxy_read_timeout` — bump it from a single field.
Disable buffering so server-pushed messages reach clients immediately.
Optionally pair the websocket location with a fallback `/` proxy to the same app.

Features

`map $http_upgrade $connection_upgrade` block included
`proxy_http_version 1.1` + Upgrade/Connection forwarding
`proxy_buffering off` for instant message delivery
Configurable idle timeout for long-lived sockets
Optional fallback `/` proxy_pass for REST + WS on one domain

How to use Nginx WebSocket Proxy Generator

Set the path. Pick the websocket location (`/ws`, `/socket.io/`, etc.).
Point at upstream. Set the websocket upstream URL (`http://...`, even for `wss`).
Set idle timeout. Raise to 3600s (or longer) for chat / pub-sub.
Deploy. Copy + drop into Nginx, `nginx -t`, reload.

Example (before/after)

Form input

path     = /ws
upstream = http://127.0.0.1:8080
idle     = 3600s

Generated config

map $http_upgrade $connection_upgrade {
  default upgrade;
  ''      close;
}
server {
  listen 80;
  server_name app.example.com;
  location /ws {
    proxy_pass http://127.0.0.1:8080;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection $connection_upgrade;
    proxy_set_header Host $host;
    proxy_buffering off;
    proxy_read_timeout 3600s;
    proxy_send_timeout 3600s;
  }
}

Common errors

WebSocket disconnects after ~60 seconds of silence

Default `proxy_read_timeout` kills idle sockets.

Fix: Bump 'Idle timeout' in this generator (e.g. 3600s) and consider keep-alive pings from the client.

Server messages arrive in batches

Nginx is buffering responses before forwarding to the client.

Fix: Generator emits `proxy_buffering off;` — keep it on. Don't override it elsewhere.

Client sees 400 / 426 Upgrade Required

The `Upgrade`/`Connection` headers aren't being forwarded.

Fix: Confirm the generated `map` block is included and that nothing rewrites those headers downstream.

FAQ

Why is the `map` directive needed?

Nginx forwards `Connection` literally by default. WebSockets need `Connection: upgrade`, but only when the client requested an upgrade. The `map` translates `$http_upgrade` to either `upgrade` or `close`, which the proxy block then forwards.

Where should the `map` block go?

At the http {} level. The generator emits it at the top of the snippet — paste it into a file under `/etc/nginx/conf.d/` so it loads inside the http context.

How does this combine with HTTPS / wss://?

The websocket location works the same on HTTPS — paste the location block into the HTTPS server generated by the SSL Config Generator. Clients connect with `wss://`.

Does it support both REST and WebSocket on the same domain?

Yes — set the optional fallback `proxy_pass` and the generator emits a `location /` block alongside the websocket location.

Should buffering be off everywhere or just here?

Just here. `proxy_buffering off` is appropriate for streaming/long-poll/websocket responses; keep it on for normal REST traffic.

What are realistic idle timeouts?

1 hour (3600s) is a reasonable upper bound for chat/realtime apps. If you go higher, also configure TCP keep-alive on the upstream so dead connections are reaped.

Related tools

WebSocket-stack neighbours. You can also browse the full DevOps & Infra category for more options.

Nginx Reverse Proxy Generator

Generate a production-ready nginx.conf for reverse proxying with proxy_pass, headers, timeouts, and gzip from a focused form

Nginx SSL Config Generator

Generate an HTTPS-ready nginx.conf with SSL certificate paths, modern protocols, ciphers, HSTS, and HTTP-to-HTTPS redirect

Nginx Load Balancer Config Generator

Generate an nginx upstream + load balancer config with round-robin, least_conn, ip_hash, weights, health checks, and keepalive

CORS Tester

Send a real OPTIONS preflight and the actual request from a server proxy and inspect the per-rule CORS verdict for any origin

HTTP Header Inspector

Paste response headers to audit HSTS, CSP, CORS, X-Powered-By disclosure, and Set-Cookie flags

Nginx Static Site Config Generator

Generate an nginx.conf for serving a static site with try_files, SPA fallback, gzip, brotli, and aggressive cache headers

Docker Compose Validator

Validate docker-compose.yml against the Compose Spec schema with hand-written lints (port collisions, undefined networks, depends_on cycles)

ENV File Editor

Edit .env files in a key/value table with type detection, masked secrets, duplicate-key warnings, and export to JSON, YAML, shell, or docker-compose

Kubernetes YAML Explorer

Explore multi-document Kubernetes manifests grouped by kind with a cross-reference graph (Service to Deployment, ConfigMap mounts, Ingress backends)