Docker foundation

Docker Foundation

Purpose

Produce container images that are small, reproducible, secure, and cache-efficient — for a backend service and for consistent local/CI environments — without baking in secrets or shipping bloated, root-running images.

When to Use

• When a service is containerized for deployment, or dev/CI needs reproducible environments.
• Not for choosing the deployment target (deployment-selection) or scaffolding app code.

Inputs

• The service's runtime (Node version), build steps, and workspace context (pnpm-workspaces/npm-workspaces).
• Deployment target expectations (deployment-selection, ../../backend/backend-deployment).

Discovery Questions

• What is the runtime + exact version, and the build → run split (compile vs serve)?
• Is this a monorepo build (workspace-aware context, pruned dependencies)?
• What must be injected at runtime (config/secrets — never built in)?

Responsibilities

• Use multi-stage builds: a build stage (deps, compile) and a lean runtime stage copying only artifacts — no toolchain, dev deps, or source in the final image.
• Pick a small, trusted, pinned base image (specific digest/tag, slim/distroless where viable) — latest is non-reproducible and a supply-chain risk (../../security/dependency-security).
• Order layers for cache efficiency: copy manifests + lockfile and install before copying source, so code changes don't bust the dependency layer (monorepo: prune to the target package's deps).
• Run as non-root: dedicated user, minimal filesystem permissions.
• No secrets in the image or build args that persist in layers — config/secrets injected at runtime (secrets-management, environment-management); use build secrets mounts if a build needs a token.
• Add a thorough .dockerignore (node_modules, .git, .env, tests) to shrink context and avoid leaking files.
• Produce reproducible, meaningful tags (immutable, e.g. content/commit-based) that ../../backend/backend-deployment promotes across environments unchanged.

Required Workflow

1. Define build vs runtime stages.
2. Pick + pin a small trusted base image.
3. Order layers for dependency caching (workspace-pruned in monorepos).
4. Set non-root user + .dockerignore.
5. Ensure runtime-injected config/secrets (none baked); define the tagging scheme.

Decision Rules

• Multi-stage always for compiled/Node services — runtime images carry artifacts, not toolchains.
• Pin base images by digest/specific tag — never latest (reproducibility + supply chain).
• Secrets are runtime, never image-layer; a secret in any layer is leaked to anyone with the image.
• One immutable image promoted across environments — differences are runtime config only (../../backend/backend-deployment).

Rules

• No secrets baked into images or persisted build args.
• Non-root runtime.
• Base images pinned; .dockerignore present.

Anti-Patterns

• Single-stage images shipping the full toolchain + source.
• FROM node:latest (non-reproducible, unvetted).
• COPY . . before installing deps (cache-busting) or without .dockerignore (leaks .env/.git).
• Secrets in ENV/build args baked into layers.
• Running as root.

Validation Checklist

• Multi-stage; lean runtime image.
• Small trusted base pinned by digest/tag.
• Layers ordered for dependency caching (workspace-pruned).
• Non-root user; .dockerignore present.
• No secrets in image/layers; runtime injection only.
• Reproducible immutable tags.

Definition of Done

Reproducible multi-stage images on a small pinned base, cache-efficient, non-root, secret-free (runtime-injected config), with a thorough .dockerignore and immutable tags ready for promotion across environments.

Related Skills

deployment-selection, ../../backend/backend-deployment, secrets-management, environment-management, pnpm-workspaces, npm-workspaces, ci-cd, ../../security/dependency-security.

Related Knowledge

../../../knowledge/ (runtime versions, target constraints).

Related References

../../../references/devops/ (Dockerfile patterns, when populated).

Context Loading Guidance

• Requires: runtime + build steps, workspace context, target expectations.
• Does not require: app feature code, deployment-target internals.
• May load: secrets-management, deployment-selection.
• Stop when: the image design (stages, base, caching, non-root, tags) is recorded.

Token Efficiency Guidance

The stage/layer plan + base-image + tag scheme is the artifact; don't paste full Dockerfiles into discussion.