WebSocket proxying in Nginx - Commands & Configuration

Introduction

WebSocket proxying lets Nginx forward WebSocket connections from clients to backend servers. This solves the problem of handling real-time communication through a reverse proxy.

When you want to serve a chat app through Nginx that uses WebSocket for live messages.

When your backend server supports WebSocket but clients connect through Nginx for security.

When you need to load balance WebSocket connections across multiple backend servers.

When you want to add SSL termination at Nginx for WebSocket traffic.

When you want to keep WebSocket connections alive and stable through a proxy.

Config File - nginx.conf

nginx.conf

events {
    worker_connections 1024;
}

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

    server {
        listen 8080;

        location /ws/ {
            proxy_pass http://localhost:9000/;
            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 86400;
        }
    }
}

This config sets up Nginx to listen on port 8080 and forward WebSocket requests from the /ws/ path to a backend server on port 9000.

The map block creates a variable $connection_upgrade that is upgrade if the client requests an upgrade, otherwise close.

The proxy_set_header directives ensure the WebSocket handshake headers are correctly passed.

proxy_read_timeout is set high to keep connections alive.

Commands

Check the Nginx configuration file syntax to make sure there are no errors before restarting.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Restart Nginx to apply the new configuration for WebSocket proxying.

Terminal

systemctl restart nginx

Expected Output

No output (command runs silently)

Test the WebSocket proxy by sending an HTTP request with WebSocket upgrade headers to Nginx.

Terminal

curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" http://localhost:8080/ws/

Expected Output

HTTP/1.1 101 Switching Protocols

Upgrade: websocket

Connection: Upgrade

Sec-WebSocket-Accept: <calculated_key>

Key Concept

If you remember nothing else from this pattern, remember: proxy_set_header Upgrade and Connection must be set correctly to enable WebSocket proxying through Nginx.

Common Mistakes

Not setting proxy_http_version to 1.1

WebSocket requires HTTP/1.1 for the upgrade handshake; without this, the connection upgrade fails.

Always set proxy_http_version 1.1 in the location block handling WebSocket.

Forgetting to set proxy_set_header Connection with the correct value

The Connection header controls if the connection upgrades or closes; wrong value breaks WebSocket handshake.

Use a map to set $connection_upgrade variable and set proxy_set_header Connection $connection_upgrade.

Not increasing proxy_read_timeout

WebSocket connections stay open long; default timeout may close them prematurely.

Set proxy_read_timeout to a high value like 86400 seconds to keep connections alive.

Summary

Configure Nginx to listen on a port and forward WebSocket requests to the backend.

Use proxy_set_header Upgrade and Connection with correct values to enable the WebSocket handshake.

Test the configuration syntax, restart Nginx, and verify the WebSocket upgrade response.