How to Set Up an Nginx Reverse Proxy for Socket.IO

iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more

Need a server to try this on? Antihost offers Linux VPS plans with NVMe storage, full root access and a 14-day free trial.

Put the Socket.IO endpoint behind an NGINX location /socket.io/ block, proxy to the Node.js service over HTTP/1.1, and explicitly forward the WebSocket upgrade headers. The essential directives are proxy_http_version 1.1, proxy_set_header Upgrade $http_upgrade, and proxy_set_header Connection "upgrade". Preserve the host and client address, and set proxy_read_timeout above Socket.IO’s heartbeat interval plus timeout (45 seconds by default; NGINX defaults to 60 seconds).

This guide covers a single Node.js process, custom paths, HTTPS, multiple Socket.IO nodes, URI-rewrite traps, validation, and the failure modes that produce disconnects or failed WebSocket upgrades.

#	Preview	Product	Price
1		Compressed Air Duster,130000RPM Super Power Cordless Air Duster,Rechargeable Brushless Blower,3 Gear...	$21.59	Buy on Amazon
2		EVEO® Screen Cleaner Spray Kit (Streak-Free) TV Screen Cleaner for Smart TV, Lcd, LEd, Oled |...	$15.97	Buy on Amazon
3		BladeHawks RGB Gaming Mouse Pad Extra Large Extended 31.5x12 Inch-Black	$14.99	Buy on Amazon
4		Vaydeer Wrist Rest for Keyboard and Mouse, Computer Ergonomic Wrist Support Pad, Soft Memory Foam...	$15.99	Buy on Amazon
5		Under Desk Cable Management Tray No Drill, Metal Mesh Cable Management Under Desk with Clamp Mount,...	$13.99	Buy on Amazon

What NGINX must do for Socket.IO

Socket.IO normally starts with HTTP long-polling and can upgrade the session to a WebSocket. NGINX sits between the browser and the Node.js process, so it must proxy both ordinary HTTP requests and the protocol switch used by WebSocket.

Upgrade and Connection are hop-by-hop headers. Proxies do not automatically pass them to an upstream server. NGINX therefore needs explicit directives that copy the client’s upgrade request and tell the upstream connection to use the upgrade. NGINX documentation describes its WebSocket tunnel mode as available since version 1.3.13 when the client requests a protocol switch and the proxied server returns HTTP 101 (Switching Protocols).

#1 Best Overall

Sale

Compressed Air Duster,130000RPM Super Power Cordless Air Duster,Rechargeable Brushless Blower,3 Gear Adjustable Blower with LED Light,Dust Remover for Computer/House/Outdoor/Car

• Powerful Turbo Fan:CAGIWIRU Electric Air Duster have reached speed up to 130000RPM,Can efficient remove dust and debris.With LED light and Three Adjustable Speed to meet with different cleaning tasks.
• With Attached USB C Fasting Charging cable.Charing 3 hours,Enjoy up to 240 minutes of use on the lowest setting, For third speed can use for 25mins.with four charging options to meet with your needs.
• Wide Application:Upgraded attached 5 different nozzles,making it suitable for a variety of scenes, such as car,pet, pc, keyboards, and other electronic devices. It also serves for office and home clean duster.
• Handy Design & Portable:Cordless air duster electric nozzle is Light weight and small size, design and comfortable to hold and space saving, convenient to carry around. You can put it in your room or inside the car without taking up space.
• Warranty & Support: Our Electric air duster comes with 5 years warranty and 24/7 customer service. During this period, if you have any questions,pls kindly feel free to contact us.

$21.59

Buy on Amazon

For the default Socket.IO path and a Node.js server listening on port 3000, the smallest reliable configuration is:

location /socket.io/ {
    proxy_pass http://127.0.0.1:3000;
    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-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 75s;
}

The first six directives are the documented reverse-proxy pattern. The 75-second timeout is an example with operational margin; select a value greater than the actual pingInterval + pingTimeout configured by your Socket.IO server.

Prerequisites and assumptions

• NGINX is installed and can be reloaded by an administrator.
• A Node.js Socket.IO server is listening on an address and port reachable from the NGINX host. The examples use 127.0.0.1:3000.
• The client connects through the same public origin that NGINX serves. If NGINX is serving static files as well, only the Socket.IO endpoint needs to be proxied.
• You know the Socket.IO path configured on the server and client. The default is /socket.io/.
• You can inspect NGINX’s error log and run nginx -t before a reload.

If the Node.js process listens on another port, private address, Unix socket, or container name, replace only the upstream address in proxy_pass. The address must be reachable from NGINX, not merely from the browser.

Configure a single Socket.IO server

1. Add a location that matches the Socket.IO path

Place the block inside the NGINX server block that serves the application’s hostname. Use location /socket.io/ for the default path. Restricting the proxy to this location lets another location / block continue serving HTML, JavaScript, images, or an API directly from NGINX.

server {
    listen 80;
    server_name example.com;

    location /socket.io/ {
        proxy_pass http://127.0.0.1:3000;
        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-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 75s;
    }
}

If NGINX fronts the entire application rather than only the Socket.IO endpoint, Socket.IO documents the same directives in location /. A broad location is appropriate when the upstream Node.js process should receive every application request; it is unnecessary when NGINX serves the rest of the site itself.

2. Check the configuration before applying it

1. Save the change in the active NGINX configuration.
2. Run nginx -t. Do not reload if the test reports a syntax or include-file error.
3. Reload NGINX using the service manager used by your system, then watch the error log while opening the application.
4. Confirm that the Node.js service is listening on the address and port named by proxy_pass.

A successful syntax test proves only that NGINX can parse the file. It does not prove that the upstream is reachable or that the Socket.IO path matches the application.

Rank #2

EVEO® Screen Cleaner Spray Kit (Streak-Free) TV Screen Cleaner for Smart TV, Lcd, LEd, Oled | Computer Screen Cleaner Spray and Wipe Microfiber Cloth - TV, Monitor, Laptop, iPad, Car - 6.7oz 1 Pack

• Screen Cleaner is Your Screen’s New Bestfriend! - EVEO is proud to present a screen cleaner that’s perfectly suited for your TV. Meet your new screen cleaner, computer screen cleaner, laptop cleaner, iPad cleaner, Macbook,tv cleaner or any other electronic device. Our screen cleaner spray and wipe along with the included plush microfiber cloth, easily removes dust, fingerprints & other smudges on the screen’s surface. Clean effectively for a streak-free screen
• Gentle on your Screens - Our screen cleaner spray and wipes is compatible to be used even for the most sensitive LCD, LED, CRT, and OLED screens in proper use. Be at ease knowing that this product is compatible with all the major brands: LG, SONY, Samsung, Sharp, iPad, iPhone, Android screens, Kindle, PC monitors - we’ve got you covered! Can be used as LCD screen cleaner, tv cleaner, smart tv screen cleaner, and more
• Premium Super Soft Plush Microfiber Cloth - Included in this efficient screen cleaning kit. This screen cleaner spray and wipe has our signature plush microfiber cloth specially designed to comply with screens and monitors and leave them streak-free. Has been shown to effectively absorbs stubborn stains, zero streaks, and no fiber shedding. Always use this together with our screen cleaner for the best results
• Easy-to-Use Screen Cleaner Kit + microfiber cleaning cloth - The EVEO Screen Cleaning Kit will easily be your new favorite tool when it comes to taking care of the things you love most, quick and easy solution for a streak-free screen. Simply screw on the sprayer gun on the screen cleaner bottle. Spray the cleaning liquid onto the microfiber cloth, then wipe the screen until desired cleanliness & shine is achieved.
• Quality Screen Care Kit Worth Purchasing - Enjoy a convenient Screen Cleaner anytime, anywhere you need it. Your satisfaction is our top priority. We stand behind the quality of our products and that’s why, you shouldn’t be worrying at all. We manufacture the Best Screen Cleaner. and can be used for laptop cleaning kit, laptop screen cleaner, tv screen cleaner for smart tv. MacBook screen cleaner, monitor cleaner or screen cleaner spray for electronic devices with microfiber cleaning cloth

$15.97

Buy on Amazon

3. Verify the browser request

Open the browser developer tools and inspect the network requests for /socket.io/. During the initial handshake you may see polling requests. When the client attempts WebSocket transport, the request should show an upgrade and receive a successful protocol-switch response from the proxy chain. A failed upgrade does not necessarily mean the Node.js code is wrong; a missing header or a location mismatch can leave polling working while WebSocket fails.

Understand the headers

Keep these directives in the location that actually matches the Socket.IO request. Defining them in a different server block, or in a location that is bypassed by a more specific match, has no effect on the connection.

Choose the proxy_pass form deliberately

NGINX treats a URI suffix on proxy_pass differently from a host-only value. When proxy_pass includes a URI, NGINX replaces the part of the request URI that matched the location. When it omits the URI, NGINX forwards the full request URI.

For the standard Socket.IO location, this form preserves the complete path:

location /socket.io/ {
    proxy_pass http://127.0.0.1:3000;
    # request path remains under /socket.io/
}

Adding a trailing URI changes the behavior:

location /socket.io/ {
    proxy_pass http://127.0.0.1:3000/;
}

That second form can silently remove or replace the portion matched by /socket.io/. Whether that is correct depends on how the Node.js server is configured. If the server expects /socket.io/, use the host-only form or verify the rewritten path explicitly. A path rewrite that affects polling but not another request can look like intermittent disconnects, so check the upstream access log as well as the browser network panel.

Prevent idle-heartbeat disconnects

NGINX closes an idle proxied connection after proxy_read_timeout, which is 60 seconds by default. Socket.IO documents a default pingInterval + pingTimeout of 45 seconds and warns that the NGINX timeout must be greater than that sum. If it is not, NGINX can close a healthy session and the client reports a transport close error.

Rank #3

BladeHawks RGB Gaming Mouse Pad Extra Large Extended 31.5x12 Inch-Black

• 【Large size】：Measuring 800 x 300 mm/ 31. 5×12 inches, which is wider and taller than others. Large mouse pad can perfectly fit your keyboard and mouse of any size, and there is also ample space for peripherals such as phones, tablets, etc.
• 【LED backlight mouse pad】：Blade Hawks RGB mouse pad provides 7 static modes and 7 dynamic modes will give you the options you are looking for. Power-off memory function remembers the last lighting mode you selected. The super glow fiber Chroma will give you a colorful gaming setup that you want.
• 【Anti-slip rubber base】：Made from Natural rubber, this gaming mousepad will firmly grip your desktop, allowing you to enjoy the ultimate precision in the games you are most passionate about. It also comes with a texture that enhances this ability even further.
• 【Smooth and waterproof surface】: Micro-textured cloth surface, for extremely precise mouse control and a smooth movement. When liquid splashes on the gaming mouse pad, it forms water droplets and slides down. Will not delay your work or gameplay.
• 【Plug and play】: This mouse and keyboard pad is powered by USB, plug and play, no driver required. One button control light modes. Press one time to change the lighting mode, press twice to change the brightness, press and hold about 3 seconds turn ON/OFF.

$14.99

Buy on Amazon

Set the timeout in the Socket.IO location:

proxy_read_timeout 75s;

Seventy-five seconds is only an example. Calculate the lower bound from the heartbeat values used by your server and client, then add enough margin for latency and scheduling. If you change Socket.IO heartbeat settings later, revisit the NGINX timeout at the same time. A long timeout does not repair an unreachable upstream; it only controls how long NGINX waits for upstream data on an otherwise established connection.

Use a custom Socket.IO path

A custom path works only when all three layers agree:

• The Socket.IO server’s path option.
• The Socket.IO client’s path option.
• The NGINX location that matches that path.

For example, if both Socket.IO endpoints use /realtime/, the proxy location must use the same prefix:

location /realtime/ {
    proxy_pass http://127.0.0.1:3000;
    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-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_read_timeout 75s;
}

Do not change only NGINX. A client still requesting /socket.io/ will miss a location intended for /realtime/, and a server listening on one path will reject requests sent to another. When diagnosing a custom path, copy the exact request URL from the browser and compare it character for character with the NGINX location and application settings.

Serve Socket.IO over HTTPS

Use an ordinary TLS-enabled NGINX server on port 443. Keep the certificate and private-key directives in that TLS server block, and place the Socket.IO proxy location inside it. The WebSocket directives do not change:

server {
    listen 443 ssl;
    server_name example.com;

    # Keep this server's existing certificate and key directives here.

    location /socket.io/ {
        proxy_pass http://127.0.0.1:3000;
        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-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 75s;
    }
}

The browser should connect through the HTTPS origin. When the client requests WebSocket from that secure page, the resulting negotiation uses the secure WebSocket scheme where applicable. Terminating TLS at NGINX does not remove the need for HTTP/1.1 or the upgrade headers on the NGINX-to-Node.js hop.

Rank #4

Sale

Vaydeer Wrist Rest for Keyboard and Mouse, Computer Ergonomic Wrist Support Pad, Soft Memory Foam Arm Cushion for Desk, Palm Hand Office Laptop Typing

• 【Softer and More Comfortable】Vaydeer wrist rest has unique diamond pattern, which is the combination of softness and aesthetics. The materials of wrist rest are improved into higher quality memory foam and covered with silky smooth lycra. The computer wrist rest makes you as comfortable and cushiony as like rest your wrists on clouds.
• 【Ergonomic Wrist Saver】The wrist rests for keyboard and mouse comes with a 17.32×3.15×0.83 inch keyboard wrist pad and a 5.94×3.15×0.83 inch mouse wrist support. Based on ergonomic design, the unique concave shape is the perfect fit for your wrist joints. The wrist rest pad fits most computer keyboards and laptops, improve hand and wrist posture, release your wrist and arm stress.
• 【Non-Slip Rubber Bottom】Featuring an anti-skid silicone base on the bottom, this wrist keyboard support stays firmly in place on your desk, preventing the padding from sliding around, ensuring stable and consistent wrist support during extended computer sessions.
• 【Better Experience & Pain Relief】Our keyboard arm rest is beneficial to alleviate the soreness caused by direct contact and friction between your arm and a hard desk surface, reducing the risk of wrist fatigue or carpal tunnel. The soft texture of memory foam can evenly distribute the pressure around your wrists and provide good support with just enough give.
• 【Helpful in Multiple Scenarios】Whether you're working, studying, writing, typing, gaming, this keyboard and mouse rest combo is an essential accessory to add comfort and support to your hands and wrists. It’s also a great gift for men, women, family, friend, coworker, gamer, teacher, etc.

$15.99

Buy on Amazon

If HTTP is redirected to HTTPS, make sure the Socket.IO client uses the final HTTPS origin rather than hard-coding an insecure WebSocket URL. Also ensure the location exists in the 443 server block; a correctly configured port-80 block cannot handle requests that arrive on port 443.

Proxy multiple Socket.IO nodes

When several Node.js processes serve Socket.IO, define an NGINX upstream group and point the Socket.IO location at it:

upstream socketio_nodes {
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
}

server {
    listen 80;
    server_name example.com;

    location /socket.io/ {
        proxy_pass http://socketio_nodes;
        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-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 75s;
    }
}

Load balancing introduces a session-affinity requirement for polling. A polling client makes successive HTTP requests, and those requests may need to reach the same Socket.IO node that owns the session state. Socket.IO documents affinity using either hash $remote_addr consistent or ip_hash. WebSocket transport uses one TCP connection for the session, so it does not make the same sequence of independent requests.

Configure the affinity method in the upstream according to your topology:

upstream socketio_nodes {
    hash $remote_addr consistent;
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
}

Alternatively, use NGINX’s ip_hash option. Both approaches bind clients by address; NAT can cause multiple users to share an address, while changing addresses can move a client between nodes. Socket.IO identifies sticky-cookie support as requiring a commercial subscription; that is the point at which a commercial NGINX edition may be evaluated if address-based affinity does not fit your deployment.

To isolate an affinity problem, temporarily force the client to use WebSocket transport only. If a single WebSocket connection works while polling fails across nodes, inspect affinity and shared session state rather than the upgrade headers.

Troubleshoot disconnects and failed upgrades

Read the logs in the right order

1. Check the browser network request to establish the exact path, query string, transport, and status.
2. Check the NGINX error log for upstream connection failures, timeout messages, or configuration mistakes.
3. Check the Node.js log to see whether the request arrived and which path the application received.
4. In a cluster, correlate the request with the node that handled it and verify that the session remains on the expected node.

This sequence distinguishes a client configuration issue from an NGINX routing issue and from an application or upstream availability issue.

Best Value

Sale

Under Desk Cable Management Tray No Drill, Metal Mesh Cable Management Under Desk with Clamp Mount, 2 Hole Cable Tray with Wire Management and Cord Organizer for Home Office Standing Desk

• 【No Drill Mounted】Cable management tray can be assembled in as little as 3 minutes or less-simply. Side clips easily clampe the edge of desk, pass through the holes on the sides, and secure excess cables with baskets. Desk cable management supports inward or outward installation to meet your needs in different scenarios, and provides you with great convenience when collecting and organizing wires.
• 【Rubber Pad Protects Desk】Wire organizer under desk built-in soft rubber pads on the clamp protect your desk from scratches, so you will not damage your furniture or office.
• 【Sturdy and Beautiful】Cord management under desk is made of high-quality carbon steel and holds about 15 lbs. The wire basket has 2 holes on each side of the tray to enable your cables to pass freely. Cable baskets are suitable for desk thickness use from 0.4" to 2.4".
• 【Space Saving & Keep Organized】Desk cable management tray holds all your power cords, outlet strips, USB hubs and computer transformers hidden from your feet, and the data cables will not enter the vacuum cleaner to keep your desk clean and tidy. Desk wire organizer is also suitable for use in the kitchen and outdoors.
• 【Reduce Safety Risks】Cable tray under desk keeps all plugs away from your kids, no more worry about tripping. Using 2 holes wire tray saves extra space, helps you easily cabling and wire protection. The mesh design is not easy to accumulate dust, but avoids safety accidents caused by messy wires.

$13.99

Buy on Amazon

Production validation checklist

• The browser and server use the same Socket.IO path.
• The NGINX location matches that path exactly enough to catch polling and WebSocket requests.
• proxy_http_version 1.1, Upgrade, and Connection are present in that location.
• Host and X-Forwarded-For are passed to the upstream.
• The selected proxy_pass form does not rewrite the path unexpectedly.
• The read timeout exceeds the configured heartbeat sum.
• The upstream address is reachable from the NGINX host.
• HTTPS clients enter the TLS server block that contains the Socket.IO location.
• Multi-node deployments have an affinity strategy for polling.
• nginx -t passes before every reload, and the error log is checked after the reload.

Reference configuration patterns

Static site plus one Node.js Socket.IO process

Use a narrow /socket.io/ location and let the existing static-file location handle everything else. This minimizes the number of requests sent to Node.js while preserving the upgrade behavior required by Socket.IO.

Node.js application behind NGINX at every path

Use the same proxy directives in location / when the Node.js process owns the complete application. In that arrangement, verify that the broad location does not override a more specific static or health-check location you intended to keep local to NGINX.

Custom endpoint

Replace /socket.io/ consistently in the client, server, and NGINX configuration. Keep the host-only proxy_pass form unless your application deliberately expects a rewritten URI.

Clustered endpoint

Use an upstream group, retain the upgrade directives in the location, and add address-based affinity when polling sessions are not shared across nodes.

Final deployment sequence

1. Confirm the Socket.IO server path, heartbeat settings, listening address, and port.
2. Select a matching NGINX location and decide whether the upstream should receive the full URI.
3. Add HTTP/1.1, upgrade, host, forwarding, and timeout directives.
4. If using HTTPS, place the location in the port-443 TLS server block.
5. If using more than one node, define the upstream and an affinity method suitable for polling.
6. Run nginx -t, reload, and inspect the logs.
7. Test initial polling, WebSocket upgrade, idle operation beyond one heartbeat interval, and reconnect behavior.

Once those checks pass, NGINX can proxy Socket.IO without treating WebSocket as an ordinary short-lived HTTP request: the upgrade reaches the Node.js server, the URI remains the one the application expects, and the proxy stays open long enough for Socket.IO’s heartbeat.

Quick Recap

SaleBestseller No. 1

Compressed Air Duster,130000RPM Super Power Cordless Air Duster,Rechargeable Brushless Blower,3 Gear Adjustable Blower with LED Light,Dust Remover for Computer/House/Outdoor/Car

$21.59

Bestseller No. 2

EVEO® Screen Cleaner Spray Kit (Streak-Free) TV Screen Cleaner for Smart TV, Lcd, LEd, Oled | Computer Screen Cleaner Spray and Wipe Microfiber Cloth - TV, Monitor, Laptop, iPad, Car - 6.7oz 1 Pack

$15.97

Bestseller No. 3

BladeHawks RGB Gaming Mouse Pad Extra Large Extended 31.5x12 Inch-Black

$14.99

SaleBestseller No. 4

Vaydeer Wrist Rest for Keyboard and Mouse, Computer Ergonomic Wrist Support Pad, Soft Memory Foam Arm Cushion for Desk, Palm Hand Office Laptop Typing

$15.99

SaleBestseller No. 5

Under Desk Cable Management Tray No Drill, Metal Mesh Cable Management Under Desk with Clamp Mount, 2 Hole Cable Tray with Wire Management and Cord Organizer for Home Office Standing Desk

$13.99

Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.