End of Life for Twilio Programmable Video - Upgrade to VideoSDKLearn More

How to Configure Nginx to Support WebSocket?

Learn how to configure Nginx to support WebSocket connections for real-time applications. This guide covers step-by-step instructions and troubleshooting tips.

Introduction to Nginx and WebSocket

In the world of web development and real-time communication, Nginx and WebSocket play pivotal roles. Nginx, a powerful web server and reverse proxy, is renowned for its high performance, scalability, and efficient handling of numerous simultaneous connections.
On the other hand, WebSocket is a communication protocol that enables interactive communication sessions between the user's browser and a server. This protocol is crucial for applications requiring real-time data exchange, such as live chats, online gaming, and financial tickers.
This article aims to provide a comprehensive guide on configuring Nginx to support WebSocket connections. By the end of this guide, you will have a clear understanding of how to set up Nginx to handle WebSocket, along with best practices for ensuring optimal performance and security.
Whether you're a developer looking to enhance your web application's capabilities or a system administrator aiming to optimize server performance, this guide will equip you with the necessary knowledge and tools.

Understanding WebSocket and Nginx

WebSocket is a protocol that allows for persistent, two-way communication between a client and a server. Unlike HTTP, which follows a request-response model, WebSocket provides full-duplex communication channels over a single TCP connection. This makes it ideal for applications that require real-time updates, such as live chats, gaming, and financial tickers.
Nginx is widely used as a web server and reverse proxy due to its performance and scalability. When combined with WebSocket, Nginx can efficiently manage and route WebSocket connections, providing a robust solution for real-time web applications. Using Nginx with WebSocket helps ensure that your application can handle a high number of simultaneous connections while maintaining low latency and high throughput.

Getting Started with Nginx for WebSocket

Before diving into the configuration, ensure you have the following prerequisites:
  • Nginx installed: You should have Nginx installed on your server. If not, we will cover the installation process.
  • Basic knowledge of Nginx configuration: Familiarity with the structure of Nginx configuration files and directives will be helpful.
This guide will walk you through the steps to configure Nginx to support WebSocket connections, ensuring your application can handle real-time communication efficiently.

Step-by-Step Configuration Guide

Step 1: Installing Nginx

First, ensure that Nginx is installed on your server. You can install Nginx using the package manager for your operating system. For example, on Ubuntu, you can use the following commands:


1sudo apt update
2sudo apt install nginx
For other operating systems, refer to the

official Nginx installation guide


Step 2: Basic Nginx Configuration

Once Nginx is installed, familiarize yourself with its configuration file, typically located at /etc/nginx/nginx.conf. A basic Nginx configuration might look like this:


1http {
2    include       mime.types;
3    default_type  application/octet-stream;
5    sendfile        on;
6    keepalive_timeout  65;
8    server {
9        listen       80;
10        server_name  example.com;
12        location / {
13            root   /usr/share/nginx/html;
14            index  index.html index.htm;
15        }
16    }
This configuration sets up a basic server listening on port 80. Next, we'll modify it to support WebSocket connections.

Step 3: Enabling WebSocket Support in Nginx

To enable WebSocket support, you'll need to configure Nginx to pass WebSocket traffic to your backend application. This involves setting the correct headers and using the proxy_pass directive. Here's an example configuration:


1http {
2    # Existing configuration
4    server {
5        listen       80;
6        server_name  example.com;
8        location / {
9            proxy_pass http://backend_server;
10            proxy_http_version 1.1;
11            proxy_set_header Upgrade $http_upgrade;
12            proxy_set_header Connection "Upgrade";
13            proxy_set_header Host $host;
14        }
15    }
This configuration ensures that WebSocket traffic is correctly handled and forwarded to the backend server.

Step 4: Handling WebSocket Connections

Handling WebSocket connections requires setting specific headers to ensure the connection upgrade request is properly managed. The following example demonstrates how to handle WebSocket connections:


1server {
2    listen 80;
3    server_name example.com;
5    location /websocket {
6        proxy_pass http://backend_server;
7        proxy_http_version 1.1;
8        proxy_set_header Upgrade $http_upgrade;
9        proxy_set_header Connection "Upgrade";
10        proxy_set_header Host $host;
11        proxy_cache_bypass $http_upgrade;
12    }
This configuration sets the necessary headers for WebSocket communication and ensures the connection upgrade is correctly processed.

Step 5: Testing the WebSocket Connection

After configuring Nginx, it's crucial to test the WebSocket connection to ensure it's working correctly. You can use tools like wscat to test the WebSocket server:


1npm install -g wscat
2wscat -c ws://example.com/websocket
Additionally, create a simple WebSocket client and server for testing purposes:


1// Simple WebSocket server
2const WebSocket = require('ws');
3const wss = new WebSocket.Server({ port: 8080 });
5wss.on('connection', ws => {
6    ws.on('message', message => {
7        console.log(`Received message => ${message}`);
8    });
9    ws.send('Hello! Message from server.');

Step 6: Troubleshooting Common Issues

When configuring Nginx with WebSocket, you may encounter common issues such as 502 Bad Gateway or 101 Switching Protocols errors. Here are some troubleshooting tips:
  • 502 Bad Gateway: Ensure your backend server is running and accessible from Nginx. Check the backend server's IP address and port in the proxy_pass directive.
  • 101 Switching Protocols: Verify that the Upgrade and Connection headers are correctly set in your Nginx configuration.
Use Nginx logs to debug issues. Check the error log (/var/log/nginx/error.log) for detailed error messages and information.

Get Free 10,000 Minutes Every Months

No credit card required to start.

Best Practices for Using Nginx with WebSocket

To ensure optimal performance and security when using Nginx with WebSocket, consider the following best practices:
  • Enable SSL/TLS: Use SSL/TLS to encrypt WebSocket connections and ensure data security.
  • Load Balancing: Use Nginx's load balancing capabilities to distribute WebSocket connections across multiple backend servers.
  • Timeouts and Limits: Configure appropriate timeouts and limits to prevent resource exhaustion and ensure stable connections.
By following these best practices, you can enhance the performance, security, and reliability of your WebSocket-enabled applications.


Configuring Nginx to support WebSocket connections is essential for building scalable, real-time web applications. By following the steps outlined in this guide, you can set up Nginx to handle WebSocket traffic efficiently, ensuring low latency and high throughput for your applications. Remember to follow best practices for performance and security to get the most out of your Nginx and WebSocket setup. With the right configuration and testing, your applications will be well-equipped to handle real-time communication needs.

Want to level-up your learning? Subscribe now

Subscribe to our newsletter for more tech based insights