Docker Highlights Summary

Every highlight bullet from the 8 pages in this section, gathered on one page and grouped by the page it came from.

The Container Model for Node.js

• A container is an isolated Linux process sharing the host kernel, not a small virtual machine
• Images are immutable, layered filesystem snapshots; containers are disposable running instances of them
• Namespaces hide host resources from the process; cgroups cap what it can consume
• Containers share a kernel with the host, so they are a weaker security boundary than a VM

Docker Basics

• Use node:24-bookworm-slim as the default production base
• Multi-stage builds keep devDependencies out of the runtime image
• npm ci --omit=dev for reproducible production installs
• Run as non-root USER node after fixing filesystem permissions
• Expose one process per container; use PORT from the environment
• Add /health and /ready endpoints for orchestrator probes

Multi-Stage Builds

• Each FROM starts a new stage; COPY --from transfers artifacts only
• Use npm ci --omit=dev in prod stage to exclude development dependencies
• Layer caching improves rebuilds when npm ci runs before source changes
• Copy package-lock.json to every stage that runs npm ci
• Native modules must compile in Linux build stage, not locally
• Run final stage as node user, never root, for security compliance

Distroless & Alpine Trade-offs

• Base image choice hinges on libc, size, and debuggability
• Alpine musl libc forces native module rebuilds for sharp, bcrypt, prisma
• Use bookworm-slim as the default for glibc and best npm compatibility
• Deploy distroless without shell or package manager for production security
• Build on Linux CI for Alpine targets, not Mac, to avoid libc mismatch
• Benchmark performance, don't assume smaller images mean faster runtime

Non-Root Containers

• Run Node.js as non-root user to block container escapes from granting host privileges
• chown files after COPY and before USER so app can read node_modules and write logs
• Use port 3000 instead of 80 for non-root; ingress maps 443 to your app port
• Set securityContext runAsNonRoot true and runAsUser 1000 in K8s manifests
• Mount emptyDir volumes for temp files when using readOnlyRootFilesystem true
• Use fsGroup in K8s securityContext to fix host volume mount permission errors

Health & Readiness Probes

• Split /health and /ready probes to stop restart cascades from temporary overload
• /health checks process only; /ready checks DB with 500ms timeout, returns 503 if down
• Startup probe allows 60 seconds for migrations before liveness probe restarts pod
• Set acceptingTraffic false on SIGTERM to gracefully drain before removing endpoints
• Move DB checks to /ready to prevent pod cascades when database briefly goes down
• Expose /health without auth so load balancers can reach it for health checks

Image Slimming

• Use .dockerignore and multi-stage builds to shrink Node.js images without breaking native modules
• Run npm ci --omit=dev inside Linux builds, never copy local node_modules into Docker
• Strip source maps from dist/ and prune test files to reduce final image size
• node_modules comprises roughly 60% of typical Express API image size; audit dependencies first
• Avoid --ignore-scripts unless safe; bcrypt and pg-native require compilation on Linux
• Never exclude package-lock.json from .dockerignore; lockfile drift breaks npm ci reproducibility

Docker Best Practices

• Multi-stage builds with npm ci --omit=dev in the runtime stage
• Run as non-root USER node after chown
• Pin base images by digest; update via Renovate PRs
• Separate /health (liveness) from /ready (dependencies)
• Scan images in CI with Trivy or Grype before deploy
• Never bake secrets or .env into image layers

3730363230327c3531386f6967637c6f692e73656469756765646f63