Notes and sources:

• Always use a syntax directive when relying on BuildKit-specific features (Docker Docs: Custom Dockerfile syntax).
• Prefer stable channel docker/dockerfile:1 for small compatibility updates, or pin a precise immutable tag when strict reproducibility is required.

Workflow

Step 1: Choose a base image strategy

Pick the smallest base image that satisfies runtime requirements.

Step 2: Structure the multi-stage build

Separate dependency installation, build, and runtime into distinct stages. Copy only production artifacts into the final stage.

Step 3: Optimize layer ordering

Place instructions that change least frequently at the top:

1. Base image
2. System packages
3. Copy lockfile → install deps
4. Copy source → build
5. Copy build output into final stage

Step 4: Use BuildKit features to speed, secure, and shrink builds

• Add an explicit syntax directive at the top of Dockerfiles that use BuildKit-specific features: # syntax=docker/dockerfile:1.
• Use cache mounts to persist package-manager caches between builds and avoid re-downloading dependencies (RUN --mount=type=cache,...). See Docker Docs: Optimize cache usage in builds.
• Use secret mounts for build-time secrets instead of ARGs or ENV so secrets are not baked into layers (RUN --mount=type=secret,id=npmrc ...). See Docker Docs: Build secrets.
• Use SSH mounts for fetching private repositories during the build (RUN --mount=type=ssh ...).

Step 5: Add security hardening

• Run as a non-root user
• Drop Linux capabilities where supported by your runtime/orchestrator
• Set read-only filesystem where possible
• Pin base image digests for reproducibility

Step 6: CI and reproducible builds

• Use docker buildx and a shared external cache (registry or GitHub Actions cache) to get repeatable, fast builds across runners
• Pin Dockerfile frontend and build tooling versions in CI
• Pin scanner and action versions; do not use @master or @latest for security-sensitive tools

Examples

Example 1: Production Next.js multi-stage Dockerfile (BuildKit primitives)

# syntax=docker/dockerfile:1

# ---- Stage 1: Dependencies ----
FROM node:22-alpine AS deps
WORKDIR /app

# Cache package manager files between builds (BuildKit cache mount)
COPY package.json pnpm-lock.yaml ./
RUN --mount=type=cache,id=pnpm-cache,target=/root/.pnpm-store \
    corepack enable pnpm && pnpm install --frozen-lockfile --prod=false

# If you need private registries, use build secrets (will not be in final layers)
# docker build --secret id=npmrc,src=$HOME/.npmrc .
# and in Dockerfile:
# RUN --mount=type=secret,id=npmrc,target=/root/.npmrc \
#     npm ci --silent

# ---- Stage 2: Build ----
FROM node:22-alpine AS build
WORKDIR /app
COPY --from=deps /app/node_modules ./node_modules
COPY . .
ENV NEXT_TELEMETRY_DISABLED=1
RUN corepack enable pnpm && pnpm run build

# ---- Stage 3: Production runner ----
FROM node:22-alpine AS runner
WORKDIR /app
ENV NODE_ENV=production
ENV NEXT_TELEMETRY_DISABLED=1
RUN addgroup --system --gid 1001 appgroup && \
    adduser --system --uid 1001 appuser

COPY --from=build /app/public ./public
COPY --from=build --chown=appuser:appgroup /app/.next/standalone ./
COPY --from=build --chown=appuser:appgroup /app/.next/static ./.next/static

USER appuser
EXPOSE 3000
ENV PORT=3000 HOSTNAME="0.0.0.0"

HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
  CMD wget --no-verbose --tries=1 --spider http://localhost:3000/ || exit 1

CMD ["node", "server.js"]

Notes:

• The # syntax= line ensures the BuildKit frontend with --mount support is used. Pin the frontend image (docker/dockerfile:1) or use an immutable tag for strict reproducibility (Docker Docs).
• Use --mount=type=cache for package manager caches (npm/pnpm/yarn) to speed CI and local rebuilds (Docker Docs: Optimize cache usage in builds).
• Provide build secrets from the CLI (docker build --secret ...) or via Buildx/Bake in CI (Docker Docs: Build secrets).

Example 2: .dockerignore template

node_modules
.next
.git
.github
.vscode
.env*
*.md
!README.md
Dockerfile*
docker-compose*
.dockerignore
coverage
.turbo
dist
.cache
*.log

Example 3: Size optimization comparison

Example 4: CI security scanning workflow (updated)

# .github/workflows/docker-scan.yml
name: Docker Build & Scan
on:
  push:
    branches: [main]
  pull_request:

jobs:
  build-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build image
        uses: docker/build-push-action@v6
        with:
          context: .
          load: true
          tags: app:scan
          cache-from: type=gha
          cache-to: type=gha,mode=max

      - name: Run Trivy scan (pin the action)
        # Pin to the patched release to avoid the March 2026 supply-chain compromise
        uses: aquasecurity/trivy-action@v0.35.0
        with:
          image-ref: app:scan
          format: table
          exit-code: 1
          severity: CRITICAL,HIGH

      - name: Optional: Additional scanners (pin versions)
        # Example: Snyk, Clair, or commercial scanners — pin the action/version you use and keep an upgrade/update process
        run: echo "Run additional image scanners here"

Security notes (Trivy March 2026 supply-chain incident):

• Do not use unpinned actions (for example @master) for security tooling. The Trivy advisory (Mar 2026) shows that using @master or latest exposed CI pipelines to malicious releases. Pin the action to the patched tag (aquasecurity/trivy-action@v0.35.0) and prefer immutable tags or digests where possible (GitHub advisory).
• Where binaries are installed directly, verify integrity (checksums/signatures) before executing. Prefer platform package managers, signed releases, or signed container images.

Decision tree

• Image is too large → switch to alpine or distroless base; enable standalone output for Next.js
• Build is slow → reorder layers so lockfile copy + install comes before source copy; use BuildKit cache mounts (--mount=type=cache) in Dockerfile and CI external caches
• CVEs in base image → pin a patched digest; run docker scout cves, Trivy (pinned), or other scanners in CI; verify scanner provenance
• Need native modules (sharp, bcrypt) → use node-slim instead of alpine; install build-essential in a builder stage only
• Reproducibility matters → pin base image by digest, not tag; use --frozen-lockfile
• Multi-platform needed → use docker buildx build --platform linux/amd64,linux/arm64

Edge cases and gotchas

1. Alpine + native modules — musl libc breaks some native Node addons (sharp, canvas). Mitigation: use node:22-slim or install libc6-compat on alpine.
2. pnpm + corepack — Docker images ship with corepack but it must be explicitly enabled. Always run corepack enable pnpm before install.
3. Next.js standalone misses public/ — the standalone output does not copy public/ or .next/static. You must COPY them explicitly in the Dockerfile.
4. COPY invalidates cache on any file change — a stale .env.local in context can bust the layer cache. Keep .dockerignore strict.
5. BuildKit must be selected (syntax directive and/or docker buildx) — use # syntax=docker/dockerfile:1 and docker buildx build or set DOCKER_BUILDKIT=1 to ensure BuildKit features (cache/secret/ssh mounts) are available (Docker Docs).
6. HEALTHCHECK vs orchestrator probes — Kubernetes ignores HEALTHCHECK; use it only for standalone Docker or Docker Compose. For K8s, define livenessProbe/readinessProbe in the pod spec.
7. Layer squashing loses cache — --squash reduces size but makes rebuilds slower. Prefer multi-stage over squashing.
8. Scanner supply-chain hardening — the March 2026 Trivy compromise demonstrates that scanner/tooling supply chains can be targeted. Mitigations:
   • Pin scanner/action versions (do not use @master or @latest) to known patched releases (GitHub advisory: patched trivy-action@v0.35.0, setup-trivy@0.2.6).
   • Prefer signed artifacts or verify checksums/signatures before running third-party binaries in CI.
   • Cache scanner images in a trusted registry and scan pull-layer digests if required.

CI security checklist (added)

• Pin scanner actions and tools by tag or digest (no @master)
• Verify scanner integrity (checksums or signatures) before execution where possible
• Use BuildKit cache mounts to reduce network fetches during CI and reduce exposure to external artifact servers
• Ensure the CI runner has minimal privileges and secrets are provided via build-time secret mounts (not ARG/ENV)

Evaluation criteria

• Final image is under 200 MB for a typical Next.js app
• Container runs as a non-root user
• No secrets or .env files baked into any layer
• docker build with warm cache completes in under 30 seconds
• Trivy or Snyk scan returns zero CRITICAL vulnerabilities (scanner pinned and verified)
• .dockerignore excludes node_modules, .git, .env*, and test artifacts
• Base image is pinned by digest or a specific minor version tag
• HEALTHCHECK or orchestrator probe is configured