docker-pro

Overview

Docker packages applications and their dependencies into portable images that run identically anywhere the Docker runtime exists. Containers are the unit of deployment for modern infrastructure — understanding images, layers, networking, and volumes is prerequisite knowledge for Kubernetes, CI/CD, and cloud platforms.

The common failure mode is treating Dockerfiles as an afterthought: bloated images, leaked secrets, and containers that work on a laptop but die in production. This skill covers writing production-grade Dockerfiles, using Compose for local development, and the security and operational practices that matter.

When to use

• Writing or reviewing Dockerfiles for any language.
• Shrinking image sizes and speeding up builds (multi-stage, layer caching).
• Setting up Docker Compose for local development environments.
• Debugging container networking, volumes, and permissions.
• Securing images (non-root users, secret handling, base image choice).
• Choosing between Docker, Podman, and other runtimes.
• Preparing images for Kubernetes or any orchestrator.

Core concepts

• Images are layered. Each Dockerfile instruction creates a layer; layers cache and reuse. Order instructions from least-frequently-changed (base image, system deps) to most-frequently-changed (app code) to maximize cache hits.
• Multi-stage builds. Build in one stage (compilers, node_modules), copy artifacts into a slim runtime stage. This is the single biggest image-size win — a Go or Java build can drop from 1GB to 50MB.
• Small base images. alpine, distroless, or -slim variants over full OS images. Smaller images pull faster, have fewer CVEs, and reduce attack surface. Distroless goes further: no shell, no package manager.
• .dockerignore. Like .gitignore for the build context — exclude .git, node_modules, build artifacts, secrets. A bloated context slows every build and can leak files into images.
• Run as non-root. Create a user and USER it. Root-in-container is still root-adjacent on the host if there's a breakout; non-root is cheap defense in depth.
• One process per container. The container's PID 1 should be your app (use exec form CMD so signals propagate). Sidecars and init systems are orchestrator concerns, not image concerns.
• Layer caching in CI. Cache layers between builds (registry cache, BuildKit cache mounts) — RUN --mount=type=cache for package managers avoids re-downloading dependencies every build.
• BuildKit. The modern builder: parallel builds, cache mounts, secrets mounts (--mount=type=secret), SSH mounts. Enable it; the legacy builder is obsolete.
• Secrets never in layers. COPY .env or ARG secrets persist in image history. Use BuildKit secret mounts or multi-stage builds that don't copy secrets into the final stage.
• Networking. Bridge (default, isolated), host (no isolation, max perf), none, and user-defined networks for inter-container DNS. In Compose, services reach each other by service name automatically.
• Volumes vs bind mounts. Named volumes for persistent data (databases), bind mounts for development (live code reload). Volumes survive container recreation; container filesystems don't.
• Healthchecks. HEALTHCHECK instruction so orchestrators know when the app is actually ready — not just when the process started.
• Compose for dev. Multi-service local environments (app + db + cache) in one YAML file. Profiles, overrides, and .env support keep dev/prod parity without production complexity.
• Image tagging. Immutable tags per build (git SHA), mutable tags (latest) only for convenience. Deployments should reference immutable digests or SHA tags — latest in production is undebuggable.
• Scanning. Scan images for CVEs in CI (Trivy, Grype, Docker Scout). Base images accumulate vulnerabilities; rebuild regularly, don't just rescan old images.

Practical workflow

1. Write the Dockerfile in cache order. Base image → system deps → language deps (lockfile first) → app code → runtime config. Each step ordered by change frequency.

   FROM node:22-slim AS deps
   WORKDIR /app
   COPY package.json package-lock.json ./
   RUN --mount=type=cache,target=/root/.npm npm ci
   

2. Use multi-stage builds. Separate build and runtime stages; copy only artifacts forward; final stage minimal.

   FROM deps AS build
   COPY . .
   RUN npm run build
   FROM node:22-slim AS runtime
   WORKDIR /app
   COPY --from=build /app/dist ./dist
   COPY --from=deps /app/node_modules ./node_modules
   RUN useradd -r app && chown -R app:app /app
   USER app
   CMD ["node", "dist/index.js"]
   

3. Add .dockerignore. Exclude .git, node_modules, *.md, local env files, and test artifacts — everything not needed at runtime.
4. Handle secrets with mounts. RUN --mount=type=secret,id=npmrc npm ci keeps tokens out of layers; never COPY credential files.
5. Define healthchecks. So orchestrators and Compose can gate on actual readiness:

   HEALTHCHECK --interval=30s --timeout=3s CMD wget -qO- http://localhost:3000/health || exit 1
   

6. Compose the dev environment. App + dependencies in compose.yaml; named volumes for databases; bind mounts for code; override files for local tweaks.

   services:
     app:
       build: .
       ports: ["3000:3000"]
       volumes: ["./src:/app/src"]
       depends_on: { db: { condition: service_healthy } }
     db:
       image: postgres:16
       volumes: ["pgdata:/var/lib/postgresql/data"]
   volumes: { pgdata: {} }
   

7. Scan and tag in CI. Build with BuildKit, scan with Trivy/Grype (fail on critical), tag with git SHA, push immutable tags.
8. Run production-ready. Resource limits, restart policies, log drivers with rotation, read-only filesystems where possible, and no --privileged without justification.

Common pitfalls

• Secrets in image layers — COPY .env or ARG credentials persist in history; use secret mounts.
• Running as root — default user is root; create and use a non-root user.
• Huge images — full OS bases and build tools in the final stage; multi-stage + slim bases.
• Cache-busting order — COPY . before npm ci invalidates the dependency layer on every code change; copy lockfiles first.
• Missing .dockerignore — slow builds and leaked files; always define it.
• Shell-form CMD — CMD npm start wraps in sh, breaking signal propagation; use exec form ["npm", "start"].
• No healthcheck — orchestrator thinks the container is ready when the process merely started; define one.
• latest in production — undebuggable deploys; pin immutable tags or digests.
• Unbounded logs — json-file logs filling disks; configure log rotation.
• Writable root filesystem — unnecessary attack surface; --read-only with tmpfs for scratch space.
• Ignoring scans — CVEs accumulating in base images; scan in CI and rebuild regularly.
• Bind mounts in production — host-path coupling; use named volumes or object storage.
• No resource limits — one container starving the host; set memory/CPU limits.