How to Enable Secure WebSocket (WSS) with Nginx: Full Configuration Guide

Understanding WebSocket and HTTP Upgrade

WebSocket and HTTP are different protocols, but their handshake is compatible; using the HTTP Upgrade and Connection headers, a connection can be upgraded from HTTP to WebSocket.

WebSocket URLs use ws:// or wss:// (the secure variant, analogous to HTTPS). Default ports are 80 for ws and 443 for wss.

Typical WebSocket Handshake

Client request:

GET / HTTP/1.1
Upgrade: websocket
Connection: Upgrade
Host: example.com
Origin: http://example.com
Sec-WebSocket-Key: sN9cRrP/n9NdMgdcy2VJFQ==
Sec-WebSocket-Version: 13

Server response:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: fFBooB7FAkLlXgRSz0BT3v4hq5s=
Sec-WebSocket-Location: ws://example.com/

Connection must be set to Upgrade to indicate a protocol upgrade request.

Upgrade header must be websocket to specify the target protocol.

Understanding wss and Nginx Proxying

WSS is WebSocket over SSL (TLS), similar to HTTPS. Nginx can proxy wss connections by converting them to plain ws for the backend (e.g., Workerman) and vice‑versa.

Client initiates a wss connection to Nginx.

Nginx converts wss data to ws and forwards it to the backend WebSocket server.

The backend processes the business logic.

Responses follow the reverse path, with Nginx converting ws back to wss for the client.

Nginx Configuration for WebSocket

Example 1: Proxy for a specific site or domain

server {
    listen 80;
    server_name your_domain;

    proxy_http_version 1.1;
    # Enable WebSocket support
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";

    location / {
        proxy_redirect off;
        proxy_pass http://myweb_backend;
        proxy_connect_timeout 60;
        proxy_read_timeout 600;
        proxy_send_timeout 600;
    }
}

Example 2: Global configuration for all sites/services

http {
    include mime.types;
    default_type text/html;
    charset utf-8;

    log_format proxy '$http_x_real_ip - $remote_user [$time_local] "$request" $status $body_bytes_sent "$http_referer" "$http_user_agent" "$http_x_forwarded_for" $request_time $upstream_response_time';
    access_log /dev/stdout proxy;

    sendfile on;
    tcp_nopush on;
    tcp_nodelay on;
    keepalive_timeout 75;
    keepalive_requests 1000;
    client_max_body_size 1020000M;
    client_body_buffer_size 256k;
    large_client_header_buffers 4 128k;
    client_header_buffer_size 32k;
    server_names_hash_max_size 512;
    server_names_hash_bucket_size 128;

    # Required WebSocket mapping
    map $http_upgrade $connection_upgrade {
        default upgrade;
        ''      close;
    }

    include /etc/nginx/conf.d/*.conf;
}

In each server or location block, add the two lines shown above to enable the upgrade:

proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;

Status Code Explanation

WebSocket uses a long‑living connection; the handshake response typically returns status code 101 (Switching Protocols), indicating the server has agreed to switch protocols.

CloseEvent Codes

The CloseEvent interface provides a read‑only numeric code (1000‑4999) that indicates why the server closed the WebSocket connection. See MDN for the full list.

When WebSocket Is Not Supported

Common console errors:

"WebSocket connection to 'ws://' failed: "

"WebSocket connection to 'ws://' failed: Error during WebSocket handshake: Unexpected response code: 400"

"WebSocket connection to 'ws://' failed: The request timed out."

Possible causes and fixes:

Proxy or firewall only allows HTTP traffic; switch to layer‑4 forwarding to support long‑living WebSocket connections.

Nginx proxy lacks proper Upgrade and Connection headers; ensure they are correctly configured as shown above.