Nginx: How to enable Web Socket connections on a NGINX Reverse Proxy

What are WebSockets?

WebSockets are a bi-directional, real-time communication protocol between a web browser (or client) and a server over the web.

Key Features:

1. Bi-directional communication: Both the client and server can send and receive data simultaneously.
2. Real-time updates: Enables instant communication, eliminating the need for page refreshes.
3. Low latency: Reduces overhead compared to traditional HTTP requests.
4. Persistent connection: Connection remains open, allowing for continuous communication.

How WebSockets Work:

1. Handshake: Client initiates connection with server using HTTP upgrade request.
2. Establish connection: Server responds, establishing WebSocket connection.
3. Data exchange: Client and server send/receive data in real-time.

Use Cases:

1. Live updates (e.g., sports scores, stock prices)
2. Real-time collaboration (e.g., Google Docs)
3. Live gaming
4. Chat applications
5. Streaming data (e.g., video, audio)

---

To enable Web Socket connections in NGINX, you need the following directives:

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_cache_bypass $http_upgrade;

Here’s an explanation of each directive:

1. proxy_http_version 1.1;

• Purpose: Specifies the HTTP version for proxy requests.
• Explanation: WebSocket connections require HTTP/1.1, which supports persistent connections. This directive ensures Nginx uses HTTP/1.1 when communicating with the upstream server.
• Default: HTTP/1.0 (which doesn’t support persistent connections)

2. proxy_set_header Upgrade $http_upgrade;

• Purpose: Forwards the Upgrade header from the client to the upstream server.
• Explanation: The Upgrade header indicates the client’s desire to establish a WebSocket connection. By forwarding this header, Nginx allows the upstream server to establish the WebSocket connection.
• Variable $http_upgrade: Contains the value of the Upgrade header sent by the client.

3. proxy_set_header Connection "upgrade";

• Purpose: Sets the Connection header to “upgrade” for proxy requests.
• Explanation: This header indicates that the client wants to establish a persistent connection. By setting it to “upgrade”, Nginx ensures the connection remains open for WebSocket communication.

4. proxy_cache_bypass $http_upgrade;

• Purpose: Bypasses caching for WebSocket connections.
• Explanation: When the Upgrade header is present (indicating a WebSocket connection), this directive prevents Nginx from caching responses. Caching would interfere with the persistent, real-time nature of WebSocket connections.
• Variable $http_upgrade: Contains the value of the Upgrade header sent by the client.

To summarize, these directives do the following:

1. Uses HTTP/1.1 for proxy requests.
2. Forwards WebSocket-specific headers (Upgrade and Connection).
3. Bypasses caching for WebSocket connections.

This configuration enables Nginx to efficiently proxy WebSocket connections to your upstream server.

Sample NGINX config file:

server {
    server_name example.com;  # Replace with your domain

    # Proxy pass the traffic to a different port
    location / {
        proxy_pass http://127.0.0.1:8080;
        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;

        # To allow websocket connections
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_cache_bypass $http_upgrade;
    }


    listen 443 ssl; # managed by Certbot
    ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; # managed by Certbot
    ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; # managed by Certbot
    include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
    ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

}
server {
    if ($host = example.com) {
        return 301 https://$host$request_uri;
    } # managed by Certbot


    server_name example.com;
    listen 80;
    return 404; # managed by Certbot

}