Configuring NGINX as a WebSocket Reverse Proxy with Node.js Example

The WebSocket protocol enables real‑time, bidirectional communication between client and server and is supported by all modern browsers. In production environments where multiple WebSocket servers are needed for performance and high availability, a load‑balancing layer that understands the protocol is required; NGINX has supported WebSocket proxying since version 1.3 (and all versions of NGINX Plus).

WebSocket handshakes are compatible with HTTP, using the HTTP Upgrade mechanism to switch from HTTP to WebSocket, which allows the use of standard ports 80 and 443 and existing firewall rules. Because WebSocket connections are long‑lived, reverse proxies must keep these connections open and forward the appropriate Upgrade and Connection headers.

To enable WebSocket proxying in NGINX, the upgrade request must be explicitly passed to the backend server. An example location block is:

location /wsapp/ {
    proxy_pass http://wsbackend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
}

After this configuration, NGINX treats the traffic as a WebSocket connection.

NGINX WebSocket Example

The following example demonstrates NGINX acting as a reverse proxy for a simple Node.js WebSocket server using the ws library. Install Node.js and npm (Ubuntu/Debian: sudo apt-get install nodejs npm; RHEL/CentOS: sudo yum install nodejs npm), create a symbolic link for node if necessary, and install ws with sudo npm install ws. If registry errors occur, reset the npm registry with sudo npm config set registry http://registry.npmjs.org/ and reinstall.

Create server.js with the following content:

console.log("Server started");
var Msg = '';
var WebSocketServer = require('ws').Server,
    wss = new WebSocketServer({port: 8010});

wss.on('connection', function(ws) {
    ws.on('message', function(message) {
        console.log('Received from client: %s', message);
        ws.send('Server received from client: ' + message);
    });
});

Run the server with node server.js. Then configure NGINX to proxy the WebSocket traffic:

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

    upstream websocket {
        server 192.168.100.10:8010;
    }

    server {
        listen 8020;
        location / {
            proxy_pass http://websocket;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
        }
    }
}

NGINX now listens on port 8020 and forwards WebSocket requests to the backend server. To test, use the wscat client (

/root/node_modules/ws/bin/wscat --connect ws://192.168.100.20:8020

). Messages typed in the client are echoed by the server and sent back through NGINX, demonstrating successful bidirectional communication.