Proxying Secure WebSocket (WSS) with Nginx: A Step‑by‑Step Guide

WebSocket uses an HTTP‑compatible handshake that can upgrade an HTTP connection to a full‑duplex WebSocket connection. This allows WebSocket services to run on standard ports 80 and 443 and to reuse existing firewall rules.

Preparation

Install nginx.

Assume the backend WebSocket server listens on port 8282.

Place the TLS certificate ( *.pem) and private key ( *.key) in /etc/nginx/conf.d/ssl.

Open port 443 on the host so that Nginx can expose a wss proxy.

Choose a distinct URL path (e.g., /wss) as the entry point to avoid interfering with existing sites. Clients will connect to wss://example.com/wss.

NGINX Configuration

WebSocket (WS) proxy

To forward a plain WebSocket connection, Nginx must forward the Upgrade and Connection headers and use HTTP/1.1.

location /ws/ {
    proxy_pass http://127.0.0.1:8282;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "Upgrade";
    proxy_set_header Host $host;
}

If you want to load‑balance several backend instances, define an upstream block and map the Connection header:

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

    upstream websocket {
        server 192.168.100.10:8010;
        server 192.168.100.11:8010;
        server 192.168.100.12:8010;
    }

    server {
        listen 80;
        server_name api.example.com;
        location / {
            proxy_pass http://websocket;
            proxy_http_version 1.1;
            proxy_set_header Upgrade $http_upgrade;
            proxy_set_header Connection $connection_upgrade;
            proxy_set_header Host $host;
        }
    }
}

Client‑side test for the plain WS endpoint:

var ws = new WebSocket("ws://api.example.com/ws");
ws.onopen = function() {
    alert("Connection opened");
    ws.send('Hello');
};
ws.onmessage = function(e) {
    alert("Message from server: " + e.data);
};

Secure WebSocket (WSS) proxy

Enable TLS on the same Nginx server and proxy the encrypted traffic to the backend WebSocket service.

server {
    listen 443 ssl;
    server_name api.example.com;

    ssl_certificate /etc/nginx/conf.d/ssl/server.pem;
    ssl_certificate_key /etc/nginx/conf.d/ssl/server.key;
    ssl_session_timeout 5m;
    ssl_session_cache shared:SSL:50m;
    ssl_protocols TLSv1 TLSv1.1 TLSv1.2;
    ssl_ciphers HIGH:!aNULL:!MD5;

    location /wss {
        proxy_pass http://127.0.0.1:8282;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Client‑side test for the secure endpoint:

var ws = new WebSocket("wss://api.example.com/wss");
ws.onopen = function() {
    alert("Secure connection opened");
    ws.send('Hello Secure');
};
ws.onmessage = function(e) {
    alert("Secure message: " + e.data);
};

With these configurations, Nginx forwards both WS and WSS traffic, preserving the required upgrade headers and TLS encryption, allowing WebSocket services to coexist with existing HTTP sites on the same host.