Containerizing Node: PID 1, signals, and slim images

PID 1 is special, and Node is not built for it

Inside a Linux container the first process started is PID 1, and the kernel treats PID 1 unlike any other process. Two rules bite Node specifically. First, PID 1 gets no default signal handlers — for a normal process the kernel installs a default action for SIGTERM (terminate), but for PID 1 there is no default, so a SIGTERM with no explicit handler is simply ignored. Second, PID 1 must reap zombies: when a child exits, its parent must wait() on it, and orphaned children are re-parented to PID 1. If PID 1 never reaps, dead children accumulate as zombies in the process table.

Node does install its own SIGTERM listener path only if you add one — but the deadly variant is starting Node indirectly. CMD npm start makes npm PID 1; npm spawns node as a child and does not forward signals to it. So the orchestrator’s SIGTERM hits npm (which ignores it as PID 1) and never reaches your application. The container appears to hang on shutdown.

# ❌ npm is PID 1; SIGTERM dies at npm, node never hears it
CMD npm start

# ❌ shell form: /bin/sh -c "node server.js" → sh is PID 1, also no forwarding
CMD node server.js

# ✅ exec form: node IS PID 1, your in-app SIGTERM handler runs
CMD ["node", "server.js"]

The shell form CMD node server.js is the same trap wearing a different hat: Docker wraps it as /bin/sh -c "node server.js", so sh becomes PID 1 and node is its child — signals stop at the shell. Always use the exec form (the JSON array) for your server so node is PID 1 directly.

Handle SIGTERM, or put an init in front of it

There are two complementary fixes, and production Node usually wants both.

The first is to run node directly (exec form) and handle SIGTERM in the app for graceful shutdown: stop accepting new connections, finish in-flight requests, close the DB pool, then exit. This is what turns a hard kill into a clean drain.

const server = app.listen(3000);

process.on("SIGTERM", () => {
  // stop taking new work, drain what's open, then exit cleanly
  server.close(() => {
    pool.end().then(() => process.exit(0));
  });
});

The second is to run an init as PID 1 so something reaps zombies and forwards signals even if your code forgets. Docker ships one: docker run --init injects tini as PID 1, which forwards SIGTERM to your node child and reaps orphans. You can also bake tini/dumb-init into the image as the ENTRYPOINT. An init matters most when your process spawns children (a build tool, a child_process, a wrapper script) — without one, those orphans become zombies.

Multi-stage builds and a slim, non-root base

A single-stage image bakes your compiler, dev dependencies, and full toolchain into what you ship. A multi-stage build splits that: a builder stage runs npm ci and the build, and a thin runtime stage copies only the artifacts it needs.

# ---- builder ----
FROM node:22 AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci                      # full deps for the build
COPY . .
RUN npm run build               # → /app/dist

# ---- runtime ----
FROM node:22-slim AS runtime
ENV NODE_ENV=production
WORKDIR /app
COPY package*.json ./
RUN npm ci --omit=dev           # prod deps only
COPY --from=builder /app/dist ./dist
USER node                       # the official image ships a non-root 'node' user
CMD ["node", "dist/server.js"]

Two details earn their keep. Copy package*.json and run npm ci before copying source. Docker caches each layer by its inputs; if the dependency layer’s inputs (the lockfile) don’t change, the whole npm ci layer is reused from cache and your slow install is skipped — only a source change invalidates the cheap COPY . . below it. (Layer caching is covered in depth in the deployment track; here the Node-specific point is lockfile before source.) And pick a slim base: a full node image is roughly 1 GB, while node:slim is a few hundred MB and a distroless Node runtime is in the tens of MB — a smaller image pulls faster and exposes a far smaller CVE surface because there’s no shell or package manager to attack.

Hardening: non-root, healthcheck, and .dockerignore

Three cheap moves separate a toy image from a production one. Run as non-root: the official node image already ships an unprivileged node user, so a single USER node line means a code-execution bug can’t trivially own the container. Add a healthcheck so the orchestrator knows when the process is actually serving — a Docker HEALTHCHECK curling a /health route, or in Kubernetes a livenessProbe/readinessProbe hitting /health and /ready; without one, a wedged process stays in the load-balancer rotation. Add a .dockerignore listing node_modules, .git, and .env: it keeps the build context small (faster builds) and, critically, prevents a committed .env from being copied into an image layer where the secret lives forever, recoverable by anyone who pulls the image.

# .dockerignore
node_modules
.git
.env
*.log

On Kubernetes the numbers tie back to PID 1: when a pod is deleted the kubelet sends SIGTERM, waits terminationGracePeriodSeconds (default 30s), and only then sends SIGKILL. If node never receives the SIGTERM (npm/shell PID 1) or has no handler, every deploy burns the full 30 seconds and then hard-kills in-flight work — exactly the hook’s slow, lossy rollout.