Complete Guide to NGINX Reverse Proxy for WebSocket with SSL (wss://) Enablement

Fundamental Principles of NGINX WebSocket Proxying

The WebSocket protocol establishes persistent connections through HTTP/1.1 upgrade mechanism. When acting as a reverse proxy, NGINX must properly handle Upgrade and Connection header fields to forward WebSocket traffic. Since version 1.3.13, NGINX natively supports WebSocket proxying without requiring additional modules.

Core Configuration Implementation

The following configuration demonstrates the basic structure for NGINX WebSocket proxying:

location /websocket/ {
    proxy_pass http://backend_host;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_read_timeout 86400;
}

Key configuration explanations:

• proxy_http_version 1.1: Enforces HTTP/1.1 protocol to support upgrade mechanism
• proxy_set_header Upgrade $http_upgrade: Forwards client upgrade requests
• proxy_set_header Connection "upgrade": Maintains connection upgrade state
• proxy_read_timeout: Sets long connection timeout duration

SSL Encryption Integration

Enable SSL in the server block to upgrade regular WebSocket to secure wss://:

server {
    listen 443 ssl;
    server_name example.com;
    
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
    
    location /websocket/ {
        proxy_pass http://backend_host;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 86400;
    }
}

Advanced Configuration Optimization

For production environments, consider adding the following optimizations:

location /websocket/ {
    proxy_pass http://backend_host;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header X-Forwarded-Proto $scheme;
    
    proxy_read_timeout 86400;
    proxy_send_timeout 86400;
    proxy_connect_timeout 60;
    
    # Buffer optimizations
    proxy_buffering off;
    proxy_buffer_size 4k;
}

Alternative Approach Comparison

While early implementations required third-party modules like nginx_tcp_proxy_module for TCP-level proxying, the official HTTP module has provided complete WebSocket support since NGINX 1.3.13. The official solution offers better compatibility and maintainability, making it the recommended approach.

Troubleshooting and Debugging

Common issues and solutions:

• Immediate connection drops: Verify correct transmission of Upgrade and Connection headers
• SSL certificate errors: Check certificate paths and permission settings
• Timeout issues: Adjust proxy_read_timeout and proxy_send_timeout values
• Missing proxy headers: Ensure all necessary header fields are properly set and forwarded

Performance Optimization Recommendations

For high-concurrency WebSocket applications:

• Implement load balancing using upstream module
• Enable TCP keepalive to reduce connection establishment overhead
• Adjust worker process count and connection limits
• Monitor proxy buffer usage patterns