Skip to content
Tutorials Center
My learning

Topics

Lesson 31 of 36 ยท Testing and Deployment

Deploying Behind nginx and TLS

Deploy Socket.IO to production: WebSocket upgrade through nginx, TLS, proxy timeouts, Docker Compose, graceful shutdown and rolling restarts.

A Socket.IO app that works on localhost:3000 often misbehaves in production for boring reasons: a proxy that does not forward the upgrade header, an idle timeout shorter than the heartbeat, a deploy that drops every connection at once. This lesson walks through a production-shaped deployment: a reverse proxy with TLS in front of Node.js, container basics, and how to restart without a storm of disconnects.

Servers, nginx and Docker cannot run on this site's runner, so configuration files are read-only. The runnable examples are small Node.js programs that demonstrate the protocol facts behind the configuration (the WebSocket handshake) and generate the config from options.

What the proxy has to do

Browsers connect to https://app.example.com. The proxy terminates TLS, then forwards plain HTTP to Node.js. For Socket.IO this must support:

  1. WebSocket upgrades. The proxy must pass Upgrade: websocket and Connection: upgrade and keep the connection open.
  2. Long idle connections. A WebSocket may be silent between heartbeats. The proxy's read timeout must be longer than pingInterval + pingTimeout (45 s by default).
  3. Sticky routing if there is more than one backend and polling is allowed (sticky sessions).
  4. Original client information (X-Forwarded-For, X-Forwarded-Proto) for logs and rate limiting.

The WebSocket upgrade, in miniature

The upgrade is an ordinary HTTP request with special headers. The server answers with status 101 Switching Protocols and a Sec-WebSocket-Accept header, computed from the client's Sec-WebSocket-Key: append a fixed GUID, hash with SHA-1, base64-encode. If a proxy strips the Upgrade header, this never happens and the client silently falls back to polling.

Node.js Compute Sec-WebSocket-Accept (RFC 6455)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

The proxy sits between these two messages. It must forward the request headers intact and then pass bytes both ways without buffering.

nginx configuration

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

upstream socket_app {
    ip_hash;                        # sticky by client IP (or use a cookie on a better balancer)
    server 127.0.0.1:3000;
    server 127.0.0.1:3001;
    keepalive 64;
}

server {
    listen 443 ssl http2;
    server_name app.example.com;

    ssl_certificate     /etc/letsencrypt/live/app.example.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/app.example.com/privkey.pem;

    location /socket.io/ {
        proxy_pass http://socket_app;
        proxy_http_version 1.1;

        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $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 120s;    # more than pingInterval + pingTimeout
        proxy_send_timeout 120s;
        proxy_buffering off;        # do not hold polling responses
    }

    location / {
        proxy_pass http://socket_app;
    }
}

server {
    listen 80;
    server_name app.example.com;
    return 301 https://$host$request_uri;
}

The map block sets Connection: upgrade for upgrade requests and close otherwise, which is more correct than hard-coding "upgrade". TLS lives in nginx; Node.js speaks plain HTTP on the local network. Since clients then reach the app through https, use wss:// automatically: io("https://app.example.com") is enough.

When Node.js sits behind a proxy, tell it so, so that client IP addresses and secure cookies are correct:

JavaScript
// Express
app.set("trust proxy", 1);
// Socket.IO: the real address is in headers
const ip = socket.handshake.headers["x-forwarded-for"]?.split(",")[0].trim() ?? socket.handshake.address;

Only trust X-Forwarded-For if the proxy overwrites it. A client can send its own header, so never use it blindly for security decisions if the app is also reachable directly.

Node.js Generate an nginx location block from options

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Containers

A typical Dockerfile and Compose file:

DOCKERFILE
FROM node:24-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev
COPY . .
ENV NODE_ENV=production
USER node
EXPOSE 3000
CMD ["node", "src/server.js"]
YAML
services:
  app:
    build: .
    environment:
      REDIS_URL: redis://redis:6379
    depends_on: [redis]
    deploy:
      replicas: 2
  redis:
    image: redis:7-alpine
  proxy:
    image: nginx:1.27-alpine
    ports: ["80:80", "443:443"]
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf:ro
      - ./certs:/etc/letsencrypt:ro
    depends_on: [app]

Run as a non-root user, expose a health route (GET /healthz returning 200 once the server and Redis are ready), and read configuration from environment variables so the same image runs everywhere.

Graceful shutdown and rolling restarts

When you deploy, the old process receives SIGTERM. If it simply exits, every client sees transport close at the same moment, then all of them reconnect to the new version together: a thundering herd, plus lost in-flight events. A kinder shutdown:

JavaScript
async function shutdown(signal) {
  console.log(`${signal}: draining`);
  healthy = false;                         // /healthz now returns 503, so the balancer stops sending new clients
  await new Promise((r) => setTimeout(r, 5000)); // let the balancer notice
  io.emit("server:restarting", { retryInMs: 3000 + Math.random() * 5000 });
  await io.close();                        // disconnect clients and stop the HTTP server
  process.exit(0);
}
process.on("SIGTERM", () => shutdown("SIGTERM"));
process.on("SIGINT", () => shutdown("SIGINT"));

Notes:

  • Restart instances one at a time and wait for the health check before the next, so the others carry the load.
  • Spread the reconnect storm: keep backoff jitter on, or send each client a random retry hint.
  • With connection state recovery clients that reconnect within the window resume without losing room broadcasts.
  • Orchestrators have a kill timeout (30 s by default in Kubernetes). Make shutdown faster than that.
  • Make clients tolerant of a new server version: do not remove or rename events in the same deploy that updates the client; deprecate first.

CDN and cloud notes

Cloudflare and most CDNs proxy WebSockets, but check the plan's idle and message limits. Some platform-as-a-service products and serverless functions cannot hold long connections; Socket.IO needs a persistent process. If you use a cloud load balancer, enable stickiness and a long idle timeout (see sticky sessions).

Environment checklist

  • TLS on, HTTP redirected to HTTPS.
  • Upgrade/Connection forwarded, read timeout above the heartbeat sum.
  • Sticky sessions or WebSocket-only clients.
  • An adapter if more than one process.
  • Health endpoint, graceful shutdown, restart one node at a time.
  • Open-file limit raised (ulimit -n, systemd LimitNOFILE) for thousands of connections.
  • Logs and metrics in place (monitoring).

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which HTTP status does the server return when a WebSocket upgrade succeeds?

    101 Switching Protocols (with Sec-WebSocket-Accept) tells the client that the connection now speaks WebSocket.
  2. 2. What should proxy_read_timeout be relative to the Socket.IO heartbeat?

    If the proxy gives up on a silent connection before the heartbeat would detect a problem, it drops healthy clients.
  3. 3. Why avoid exiting immediately on SIGTERM during a deploy?

    Draining first (fail health checks, notify clients, close cleanly) reduces dropped events and the reconnect storm.
  4. 4. Why can X-Forwarded-For not be trusted blindly?

    Headers are controlled by the sender. Trust them only when set by your own proxy and the app is not directly reachable.

Summary

  • The proxy must forward Upgrade/Connection, keep long timeouts and preserve client information.
  • TLS ends at the proxy; clients use https/wss automatically.
  • Containerize with a non-root user, a health route and environment-based config.
  • Shut down gracefully and restart one node at a time to avoid a reconnect storm.
  • Raise file descriptor limits and plan for sticky sessions and an adapter when scaling.

Next: Monitoring and Debugging