containers

Containers

Purpose

Build container images that are small, cached effectively, and safe to run — not a 1.2 GB image running as root that rebuilds from scratch every time a source file changes.

When to Use

• Writing or reviewing a Dockerfile.
• Reducing image size or build time.
• Debugging a container that exits, hangs, or behaves differently from local development.
• Hardening images before a security review.

Capabilities

• Multi-stage builds and build-cache optimization.
• Base-image selection: distroless, Alpine, slim, and their trade-offs.
• Non-root users, read-only filesystems, and dropped capabilities.
• Signal handling and PID 1 semantics.
• Image scanning and SBOM generation.

Inputs

• The application, its runtime, and its build steps.
• The target platform (including whether ARM builds are required).
• Security and compliance requirements.

Outputs

• A multi-stage Dockerfile with an ordered, cache-friendly layer sequence.
• An image running as a non-root user, with no build tooling inside.
• A scan report with no critical vulnerabilities in the final image.

Workflow

1. Order layers by change frequency — Dependency manifests first, dependency install second, source code last. Copying the source before installing dependencies invalidates the cache on every code change.
2. Build in stages — A build stage with compilers and dev dependencies; a runtime stage containing only the artifact and its runtime. The compiler must not ship to production.
3. Run as non-root — Create a user in the image and USER it. A container running as root that is compromised is a root process on the node.
4. Handle signals — Use exec form (CMD ["node", "server.js"]), not shell form. Shell form makes /bin/sh PID 1, which does not forward SIGTERM, so your graceful shutdown never runs.
5. Scan and pin — Pin the base image by digest, scan the final image, and rebuild regularly to pick up base-image patches.

Best Practices

• COPY package*.json ./ then RUN npm ci then COPY . . — in that order. This is the single most impactful Dockerfile optimization and it is routinely written backwards.
• Shell-form CMD means your process is not PID 1 and will not receive SIGTERM. Every "why doesn't my container shut down gracefully" question has this answer.
• Distroless or scratch images have no shell, which is excellent for security and inconvenient for debugging. Use kubectl debug or a debug variant tag.
• A .dockerignore that excludes .git, node_modules, and build output can cut the build context from hundreds of megabytes to a few.
• latest is not a version. Pin by digest for reproducibility, or at minimum by an immutable tag.
• Secrets passed as build args are baked into the image layers and recoverable. Use BuildKit secret mounts.