docker

Default output: return only the result, blockers, and required evidence. Omit preambles, process narration, repeated context, confidence scores, and follow-up offers. Use at most five bullets unless a required artifact or schema needs more.

Docker Container Engineering

Current Versions (Verify Before Use)

docker --version          # Engine version
docker compose version    # Compose plugin version
docker buildx version     # BuildKit/buildx version

Check the Docker Engine release notes for the latest stable.

Core Principles

Multi-stage builds are the default. Every production Dockerfile should use multi-stage builds to minimize attack surface and image size.
Non-root containers. Every container should run as a non-root user unless impossible.
Layer caching is a first-class concern. Order Dockerfile instructions from least-frequently-changing to most-frequently-changing.
Healthchecks are mandatory. Every long-running container must define a HEALTHCHECK.
Scan before push. Every image should pass a security scan before registry upload.

Dockerfile Review Checklist

Structure

Uses multi-stage build (at least 2 stages: builder + runtime)
Base image is a slim or distroless variant (alpine, slim, distroless)
No latest tag — pinned to specific digest or version
WORKDIR is set before file operations
COPY uses specific files, not COPY . . where possible

Security

Runs as non-root (USER directive or --user at runtime)
No secrets in layers (use BuildKit secrets or runtime mounts)
EXPOSE documents only necessary ports
HEALTHCHECK is defined
No unnecessary packages installed (apt-get cleaned, no dev tools in runtime)
Image scanned with docker scout or Trivy

Efficiency

.dockerignore exists and excludes: .git, node_modules, *.log, .env
Layer order respects cache invalidation (dependencies before code)
RUN commands combined where logical (but not excessively long)
BuildKit enabled (DOCKER_BUILDKIT=1 or default in modern Docker)

Multi-Stage Build Template

# syntax=docker/dockerfile:1
FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json .
RUN npm ci --only=production

FROM node:22-alpine AS runtime
RUN addgroup -g 1001 -S nodejs && adduser -S nodejs -u 1001
WORKDIR /app
COPY --from=builder --chown=nodejs:nodejs /app/node_modules ./node_modules
COPY --chown=nodejs:nodejs . .
USER nodejs
EXPOSE 3000
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
  CMD node -e "require('http').get('http://localhost:3000/health', (r) => r.statusCode === 200 ? process.exit(0) : process.exit(1))"
CMD ["node", "server.js"]

Docker Compose Patterns

Development vs Production Separation

# docker-compose.yml — production baseline
services:
  app:
    build: .
    restart: unless-stopped
    deploy:
      resources:
        limits:
          cpus: '1.0'
          memory: 512M
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
      interval: 30s
      timeout: 3s
      retries: 3

# docker-compose.override.yml — development only
services:
  app:
    volumes:
      - .:/app
    environment:
      - NODE_ENV=development
    command: npm run dev

Validation

docker compose config              # validate and merge
docker compose config --profiles   # check profile separation

Security Scanning

# Docker Scout (built-in, requires login)
docker scout quickview myimage:latest
docker scout cves myimage:latest

# Trivy (open source)
trivy image myimage:latest
trivy filesystem .

# Snyk
snyk container test myimage:latest

Common Anti-Patterns

Anti-Pattern	Why It's Wrong	Fix
`FROM node:latest`	Non-reproducible builds, surprise updates	Pin to `node:22-alpine` or digest
Running as root	Container escape = host compromise	`USER` directive + file ownership
`COPY . .` without `.dockerignore`	Bloats image, leaks secrets	Explicit `.dockerignore`
`apt-get update && apt-get install` without cleanup	Bloated layers	`&& rm -rf /var/lib/apt/lists/*`
No healthcheck	Orchestrator can't detect failure	`HEALTHCHECK` in Dockerfile or compose
Secrets in ENV	Visible in `docker inspect`	BuildKit secrets or runtime mounts
Single-stage build	Large attack surface, slow deploys	Multi-stage: build → runtime

CI/CD Integration

# .github/workflows/docker.yml
- name: Build and scan
  run: |
    docker build -t app:${{ github.sha }} .
    docker scout cves app:${{ github.sha }} --exit-code --only-severity critical,high
    docker run --rm app:${{ github.sha }} npm test

Troubleshooting Flow

Build fails: Check layer cache — docker build --no-cache to isolate
Image too large: Run dive myimage:latest to analyze layer bloat
Container exits immediately: Check CMD/ENTRYPOINT and logs (docker logs)
Permission denied: Verify USER directive and file ownership in COPY --chown
Healthcheck failing: Test command inside container with docker exec

About this skill