Docker & Container Engineering Standards

This skill codifies 2026 Docker best practices — secure, minimal, reproducible container images using BuildKit, multi-stage builds, and Compose v2.

1. Dockerfile Fundamentals

Always Start With BuildKit Syntax

# syntax=docker/dockerfile:1

Place this as the first line of every Dockerfile. It enables:

• Parallel stage execution
• Cache mounts (--mount=type=cache)
• Secret mounts (--mount=type=secret)
• Reproducible builds across Docker versions

Base Image Selection

• NEVER use :latest — always pin to a specific version tag
• Prefer `-slim` variants over full images to reduce attack surface
• Consider `distroless` for production — no shell, no package manager = minimal attack surface

2. Multi-Stage Builds (Required for Production)

Multi-stage builds are mandatory for any production image. They separate build-time dependencies from runtime. See [templates.md](references/templates.md) for the full annotated Multi-Stage Build template.

Key Rules

• Name every stage: FROM ... AS builder — makes builds readable and targetable
• Copy only artifacts: Use COPY --from=builder to cherry-pick built files
• Never install dev dependencies in the runtime stage
• The runtime stage should have ZERO build tools (no compilers, no git, no curl)

3. Security Hardening

Non-Root Execution (Mandatory)

# Create a system user with no home directory, no login shell
RUN groupadd -r appgroup && useradd -r -g appgroup -s /usr/sbin/nologin appuser

# Switch to the non-root user BEFORE CMD
USER appuser

• NEVER run containers as root in production
• NEVER use --privileged flag unless absolutely required
• Set `USER` as late as possible — after all RUN commands that need root

Secret Handling

# ✅ Good: BuildKit secret mount (never stored in layers)
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) \
    npm config set //registry.npmjs.org/:_authToken=$NPM_TOKEN

# ❌ Bad: ARG/ENV secrets (visible in image history)
ARG NPM_TOKEN
ENV NPM_TOKEN=$NPM_TOKEN

• NEVER use ARG or ENV for secrets — they are baked into image layers
• NEVER COPY .env files into the image
• Use --mount=type=secret (BuildKit) for build-time secrets
• Use Docker Compose secrets: or orchestrator secrets for runtime

Vulnerability Scanning

docker scout cves <image>          # Docker Scout
trivy image <image>                # Trivy (open source)
grype <image>                      # Grype (Anchore)

• Run scanning in CI — hard-fail on HIGH/CRITICAL vulnerabilities
• Never use continue-on-error: true for security gates

4. Layer Optimization

Instruction Ordering

Docker caches each layer. Order instructions from least-changing to most-changing:

# 1. Base image (rarely changes)
FROM node:22-slim

# 2. System deps (changes infrequently)
RUN apt-get update && apt-get install -y --no-install-recommends \
    dumb-init \
    && rm -rf /var/lib/apt/lists/*

# 3. Application deps (changes when lock file changes)
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

# 4. Application code (changes most frequently)
COPY . .
RUN pnpm build

Cache Mounts (BuildKit)

# Cache package manager downloads between builds
RUN --mount=type=cache,target=/root/.cache/pip \
    pip install -r requirements.txt

.dockerignore (Required)

Create a .dockerignore in every project with a Dockerfile:

.git
.github
node_modules
dist
*.md
.env*
.vscode
.idea
tmp/
coverage/

• ALWAYS exclude .git — it can be hundreds of MB
• ALWAYS exclude node_modules — reinstall inside the container
• ALWAYS exclude .env* — prevents secret leaks

5. Advanced Examples & CI/CD

For advanced Docker Compose configurations and GitHub Actions CI/CD workflows, see the reference file:

[Read: references/advanced-examples.md](references/advanced-examples.md)

7. Anti-Patterns (Never Do These)