Skip to content

Use Nginx as reverse proxy for WebSocket

WebSocket is a computer communications protocol, providing full-duplex communication channels over a single TCP connection. The WebSocket protocol was standardized by the IETF as RFC 6455 in 2011. The current API specification allowing web applications to use this protocol is known as WebSockets.


WebSocket protocol can communicate multiple times after a successful handshake, unlike HTTP protocol, until the connection is closed. However, the handshake in WebSocket is compatible with the handshake in HTTP, and it uses the Upgrade protocol header in HTTP to upgrade the connection to WebSocket.

WebSocket Connection HTTP Connection
WebSocket is a bidirectional communication protocol that can send the data from the client to the server or from the server to the client by reusing the established connection channel. The connection is kept alive until terminated by either the client or the server. The HTTP protocol is a unidirectional protocol that works on top of TCP protocol which is a connection-oriented transport layer protocol, we can create the connection by using HTTP request methods after getting the response HTTP connection get closed.
Almost all the real-time applications like (trading, monitoring, notification) services use WebSocket to receive the data on a single communication channel. Simple RESTful application uses HTTP protocol which is stateless.
All the frequently updated applications used WebSocket because it is faster than HTTP Connection. When we do not want to retain a connection for a particular amount of time or reuse the connection for transmitting data; An HTTP connection is slower than WebSockets.

WebSocket works on HTTP ports 80 and 443 and is labeled with the prefix ws:// or wss://. It uses the HTTP/1.1 101 status code for protocol switching during connection establishment. The current standard does not support establishing WebSocket connections directly between two clients without HTTP.

NGINX has supported WebSocket since version 1.3.

Confirm nginx version

Make sure nginx version is greater than 1.3.

nginx -v

Add ws configuration

Add the following content to the http section of nginx configuration file, where upstream is the address of the upstream ws service.

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

upstream websocket {
    server localhost:8282;
  • proxy_read_timeout: Syntax proxy_read_timeout time Default value 60s Context http server location Description This directive sets the read timeout with the proxy server. It determines how long nginx waits to receive the response to a request. This time is not for obtaining the entire response but for the time between two reading operations.
  • proxy_send_timeout: Syntax proxy_send_timeout time Default value 60s Context http server location Description This directive sets the timeout for sending a request to the upstream server. The timeout is not for the entire sending period but for the time between two writing operations. If there is no new data received by upstream after timeout, nginx will close the connection.

Also add server configuration

server {
    server_name YOUR_SERVER_NAME;
    listen 80;
    location / {
       proxy_pass http://websocket;
       proxy_read_timeout 300s;
       proxy_send_timeout 300s;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection $connection_upgrade;

Restart nginx

nginx -t
nginx -s reload



Back to Table of Contents

  1. License under CC BY-NC 4.0
  2. Copyright issue feedback, replace # with @
  3. Not all the commands and scripts are tested in production environment, use at your own risk
  4. No personal information is collected.