WebSocket proxy through nginx: configuration for persistent connections

WebSocket connections through an nginx proxy drop after 60 seconds or fail to upgrade, with clients seeing connection errors or silent disconnections.

Configure nginx to handle the HTTP upgrade handshake and extend timeouts:

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

server {
    listen 443 ssl;
    server_name example.com;

    location /ws/ {
        proxy_pass http://127.0.0.1:3000;
        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;

        # Prevent nginx from closing idle WebSocket connections
        proxy_read_timeout 3600s;
        proxy_send_timeout 3600s;
    }
}

Also send application-level pings to keep the connection alive:

// Server-side ping every 30 seconds
setInterval(() => {
  wss.clients.forEach(ws => {
    if (ws.isAlive === false) return ws.terminate();
    ws.isAlive = false;
    ws.ping();
  });
}, 30000);

HTTP/1.1 WebSocket upgrade requires specific headers to switch protocols. The default nginx read_timeout of 60s kills idle connections.