docker

Docker — Images & Compose

An image is a liability proportional to its size and privilege: every MB ships, every package is attack surface, every root container is a host risk. The craft is small, reproducible, least-privilege images. CI/CD, registries, and orchestration belong to deployment-cicd; this skill is the Dockerfile and compose itself.

Lint a Dockerfile against the rules below: bash scripts/lint_dockerfile.sh path/to/Dockerfile

Multi-stage — build fat, ship thin

# Wrong — toolchain + source + caches all ship; 1.2 GB; runs as root
FROM node:26
COPY . .
RUN npm install && npm run build
CMD ["node", "dist/server.js"]

# Correct — build stage discarded; runtime carries only the artifact; ~180 MB
FROM node:26-slim AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci                      # ci (not install) = reproducible, lockfile-exact
COPY . .
RUN npm run build

FROM node:26-slim AS runtime
WORKDIR /app
ENV NODE_ENV=production
COPY --from=build /app/dist ./dist
COPY --from=build /app/node_modules ./node_modules
USER node                       # never run as root
EXPOSE 8080
HEALTHCHECK CMD node healthcheck.js || exit 1
CMD ["node", "dist/server.js"]

The build stage carries compilers and dev deps; the runtime stage copies only the artifact. Result is smaller, faster to pull, and has less attack surface. Full optimization → references/dockerfile-optimization.md.

Layer cache — order from least to most volatile

# Wrong — any source change busts the dependency layer; npm ci re-runs every build
COPY . .
RUN npm ci

# Correct — deps cached until package*.json changes; source edits skip the install
COPY package*.json ./
RUN npm ci
COPY . .                        # volatile source last

Docker caches per layer; a layer rebuilds when its inputs or any prior layer changes. Put rarely-changing things (dependency manifests, RUN apt install) before frequently-changing things (source). A .dockerignore (excluding node_modules, .git, *.log) keeps the build context — and the cache key — small.