How do you proxy WebSocket connections through Nginx?

A WebSocket starts as an HTTP Upgrade request. Nginx must forward both the Upgrade and Connection headers to the backend. The Connection header is hop-by-hop, so a map avoids sending upgrade semantics on ordinary requests.

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

server {
    location /ws/ {
        proxy_pass http://backend;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
        proxy_set_header Host $host;
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
        proxy_buffering off;
    }
}

Production concerns

• Sticky routing or a shared pub/sub layer is needed when multiple backend instances hold socket state
• Load balancers and firewalls may close idle connections before Nginx does
• The application should send heartbeats or ping frames to detect dead peers
• Authentication usually happens during the HTTP handshake, not after the upgrade
• An upgraded connection leaves the upstream keepalive pool and stays dedicated for the socket lifetime