Containerize a Node.js Service

What you'll build

A Node.js HTTP service in an image built from node:24-alpine, installing only production dependencies with a reproducible npm ci, running as the built-in node user and shutting down cleanly on SIGTERM.

The idea

• npm ci, not npm install: it installs exactly what package-lock.json says and fails if the lockfile is out of date, so builds are reproducible.
• --omit=dev skips test and build tooling in the runtime image. If you need a build step (TypeScript, bundlers), do it in a separate build stage.
• The official Node images include a non-root node user (UID 1000).
• Node doesn't install a SIGTERM handler by default; as PID 1 it simply ignores the signal. Handle it: stop accepting connections, finish in-flight requests, exit.
• Set NODE_ENV=production: many libraries switch to faster, quieter behaviour.

The code

trap 'docker rm -f rc-node > /dev/null 2>&1; docker image rm -f rc-node:1 > /dev/null 2>&1' EXIT
cat > package.json <<'EOF'
{ "name": "orders", "version": "1.0.0", "private": true, "type": "module", "main": "server.js" }
EOF
cat > package-lock.json <<'EOF'
{ "name": "orders", "version": "1.0.0", "lockfileVersion": 3, "requires": true,
  "packages": { "": { "name": "orders", "version": "1.0.0" } } }
EOF
cat > server.js <<'EOF'
import http from "node:http";
const server = http.createServer((req, res) => res.end(JSON.stringify({ ok: true, env: process.env.NODE_ENV })));
server.listen(3000, () => console.log("listening on 3000"));
process.on("SIGTERM", () => {
  console.log("SIGTERM received: closing server");
  server.close(() => process.exit(0));
});
EOF
cat > Dockerfile <<'EOF'
FROM node:24-alpine
ENV NODE_ENV=production
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci --omit=dev
COPY server.js .
USER node
CMD ["node", "server.js"]
EOF
docker build -q -t rc-node:1 . > /dev/null
docker run -d --name rc-node rc-node:1 > /dev/null
sleep 1
start=$(date +%s%N); docker stop rc-node > /dev/null; end=$(date +%s%N)
docker logs rc-node
ms=$(( (end - start) / 1000000 ))
[ "$ms" -lt 3000 ] && echo "docker stop finished in under 3 s (no 10 s timeout)"
echo "exit code: $(docker inspect rc-node --format '{{.State.ExitCode}}'), ran as: $(docker image inspect rc-node:1 --format '{{.Config.User}}')"

listening on 3000
SIGTERM received: closing server
docker stop finished in under 3 s (no 10 s timeout)
exit code: 0, ran as: node

Common mistakes

• npm install in the image, which can update the lockfile and produce different trees on every build.
• Copying node_modules from the host (wrong platform binaries); add it to .dockerignore.
• No SIGTERM handler: every deploy and scale-down waits for the 10 to 30 second kill timeout and drops connections.
• Using npm start as the command: npm becomes PID 1 and older versions don't forward signals; call node directly.

Key points

• npm ci --omit=dev with a committed lockfile for reproducible, lean images.
• Run as the node user, set NODE_ENV=production.
• Handle SIGTERM and start node directly.

Further reading: npm ci · Node.js Docker best practices