Dockerizing Real-Time Services: CI/CD for WebSocket and SFU Apps

A rolling deploy is invisible for a stateless HTTP service: drain the connections, which take milliseconds, replace the container, move on. Do the same thing to a WebSocket service and you have just disconnected everyone it was holding — and to an SFU, you have ended everybody's call. The orchestrator did exactly what it was told. What it was told assumed requests are short.

This is the capstone of the deployment series and the hardest case in it: containerising and continuously deploying services whose whole purpose is to hold a connection open.

The mismatch

Why the defaults are wrong here

The image

Container basics that matter more for stateful services

FROM node:20-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:20-slim
WORKDIR /app
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules

# EXEC form, so node is PID 1 and receives SIGTERM directly.
# The shell form (CMD node dist/server.js) runs it under /bin/sh, which does
# NOT forward signals — your drain handler never fires and every deploy
# becomes a hard kill. This one line is the whole difference.
CMD ["node", "dist/server.js"]

# Two endpoints, not one. See below.
HEALTHCHECK --interval=10s --timeout=3s CMD node dist/healthcheck.js

Liveness and readiness are different questions

Collapsing these into one endpoint is the most common mistake in this whole area, and it produces a specific, confusing symptom: containers restarting during every deploy, disconnecting the clients they were mid-way through handing over.

The deploy

Drain, do not replace

let draining = false;

app.get('/healthz', (_, res) => res.sendStatus(200));            // alive, even draining
app.get('/readyz',  (_, res) =>
  res.sendStatus(draining || sockets.size >= MAX_CONNS ? 503 : 200));

process.on('SIGTERM', async () => {
  draining = true;                       // /readyz goes red; no new routing here

  // Give the load balancer time to notice before we push anyone off.
  await sleep(5_000);

  for (const socket of sockets) {
    socket.send(JSON.stringify({
      type: 'reconnect',
      after_ms: Math.floor(Math.random() * 60_000),   // scatter the herd
    }));
  }

  const deadline = Date.now() + 90_000;  // < terminationGracePeriodSeconds
  while (sockets.size > 0 && Date.now() < deadline) await sleep(1_000);

  log.info('drained', { remaining: sockets.size });
  server.close(() => process.exit(0));
});

The five-second pause before notifying anyone is easy to leave out and it matters: without it, clients start reconnecting while the load balancer still considers this instance ready, and a portion of them land straight back on the container that is trying to empty.

Media

SFUs break two more assumptions

Everything above applies to an SFU, plus two problems that are specific to media.

1. UDP media ports are not HTTP and your ingress does not understand them

   An SFU needs a wide UDP range reachable directly, and clients negotiate a specific address during ICE. Standard HTTP ingress does nothing for this: the media path is hostPort or host networking, with the node's public address advertised explicitly in the SFU config. Getting this wrong produces the classic symptom — signalling connects, participants appear, nobody can hear anyone.

2. A room cannot move

   Everyone in a call is pinned to one SFU instance. There is no draining a room to another node without renegotiating every participant. So the deploy unit is effectively the room: stop assigning new rooms to an instance, wait for its existing ones to end, then replace it.

Pipeline

What CI has to do differently

• Tag by commit SHA, never latest. With connection draining a deploy spans minutes and both generations run simultaneously; latest makes it impossible to say which container is which, exactly when you need to.
• Set maxSurge: 1, maxUnavailable: 0 so the new instance is serving before the old one starts emptying. This needs headroom for both — draining costs capacity as well as time.
• Grace period longer than the drain deadline, always. If your drain waits 90 seconds, the grace period is 120. Getting this backwards silently reverts you to hard kills.
• Gate the rollout on connection count, not on HTTP checks. A new instance that is up but has not yet accepted a socket has proved nothing.
• Deploy on a schedule for media services. Continuous deployment and hour-long calls are in genuine tension. A nightly window is not a failure of engineering, it is reading the constraint correctly.

Honesty about what is left

• Deploys are slow now. Minutes rather than seconds. That is the cost of not disconnecting people, and it makes "deploy twenty times a day" impractical for these services specifically.
• Reconnecting clients lose ephemeral state. Anything held only in the socket's memory is gone. It has to be recoverable from the server after a reconnect, which is a design requirement that reaches into the application.
• Autoscaling still needs custom metrics. Connections per instance, exported and scaled on. CPU-based autoscaling will not do anything useful.
• This does not survive a node failure. Draining is graceful shutdown; a machine that vanishes takes its connections with it, and the client's reconnect logic is the only mitigation.
• Test the drain path in CI. Start the container, open sockets, docker stop, assert the reconnect frames were sent and the process exited zero. It is the code most likely to rot silently, because nothing else exercises it.

The checklist

• Exec-form CMD so the process is PID 1 and receives SIGTERM.
• Separate /healthz and /readyz — liveness stays green while draining.
• Readiness also red at the connection ceiling, not only when draining.
• Pause after going unready before notifying clients.
• Jittered reconnect instructions, never a mass disconnect.
• Grace period > drain deadline > jitter window.
• maxSurge: 1, maxUnavailable: 0, with capacity for both generations.
• Image tags by commit SHA.
• SFU media ports on host networking, with the public address advertised explicitly.
• A CI test for the drain path, because nothing else will catch it breaking.

Where to start on Monday

Run docker stop on your real-time container and watch the logs. If your drain handler does not log anything, you have the shell-form CMD problem, and every deploy you have ever done was a hard kill. That is a five-minute check and a one-line fix.

• exec-form CMD
• liveness vs readiness
• connection draining
• jittered reconnect
• grace period
• maxSurge
• SHA tags
• host networking

This closes the deployment series: the environments, securing the box, the pipeline, the atomic swap, and now the stateful case. The architecture this deploys is in adding real-time to microservices, and the drain pattern first appears in the WebSocket pillar.