Complete Guide to Configuring WebSocket Proxy Support in Nginx

Understanding WebSocket and Nginx Proxy Integration

WebSocket is a full-duplex communication protocol built on TCP. It allows persistent connections between clients and servers, making it ideal for real-time applications like live chats, data push systems, and interactive dashboards. In many setups, a proxy server like Nginx is used to route WebSocket traffic efficiently and securely.

Setting Up Nginx

Before configuring support for WebSocket, ensure Nginx is installed on your server. Depending on your operating system, you can install it using package managers or build it from source.

Configuring Nginx for WebSocket Support

Open the Nginx main configuration file, typically located at /etc/nginx/nginx.conf, and add the following directives inside the http block:

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

upstream backend {
    server 127.0.0.1:8080;
}

The map directive processes the Upgrade header from incoming requests to determine whether to keep the connection open. The upstream block defines the backend server handling the WebSocket requests.

Next, add the following configuration inside the relevant server block to handle WebSocket traffic:

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

This section ensures that WebSocket requests to the /websocket path are correctly proxied to the backend while preserving the necessary headers for protocol negotiation.

Restarting Nginx to Apply Changes

After saving the updated configuration, reload or restart Nginx using the following command:

<span class="fun">sudo service nginx restart</span>

Make sure there are no syntax errors and that the ports are correctly assigned before restarting the service.

Testing the WebSocket Connection

Once the Nginx configuration is active, you can test the WebSocket functionality using a simple frontend example. Here is a JavaScript snippet:

var ws = new WebSocket("ws://your_domain/websocket");

ws.onopen = function() {
    console.log("Connected to WebSocket");
};

ws.onmessage = function(event) {
    console.log("Received message: " + event.data);
};

ws.onclose = function() {
    console.log("Disconnected from WebSocket");
};

Embed this code into an HTML file and open it in a browser. If the browser's console logs “Connected to WebSocket,” your configuration is successful.

Conclusion

By following these steps, you can enable WebSocket protocol support using the Nginx proxy server. This setup is highly effective for building real-time applications while leveraging Nginx’s performance and scalability. It's important to note that Nginx acts solely as a proxy in this setup—the actual WebSocket server logic must still be implemented on the backend.