dockerfile

name	dockerfile
description	Generates and validates production-ready multi-stage Dockerfiles and .dockerignore files with BuildKit features, pnpm monorepo support, OCI labels, and security hardening. Use when creating, editing, reviewing, or validating Dockerfiles for Node.js, Python, Go, Java, or Rust.

[H1][DOCKERFILE]

Dictum: Structured generation and validation produce secure, minimal container images.

Docker Engine 27+ | BuildKit 0.27+ | Dockerfile syntax 1.14 | Node 24 LTS Krypton | Alpine 3.23

Tasks:

1. Gather requirements -- language, version, framework, entry point, package manager
2. Read dockerfile_knowledge.md -- Generation patterns and language substitution
3. (framework research) Query context7 MCP or WebSearch for "<framework> <version> dockerfile production 2026"
4. Generate Dockerfile -- Apply universal template with language-specific substitution
5. Generate .dockerignore -- See exemplar at examples/example.dockerignore
6. Validate -- Read validation.md and apply 5-stage pipeline (hadolint + Checkov + custom)
7. Iterate -- Fix, re-validate, repeat (max 3 iterations)

Scope:

• Generation: Dockerfiles for Node.js (pnpm/npm), Python (uv), Go, Java, Rust
• Validation: All Dockerfile variants (Dockerfile, Dockerfile.prod, Dockerfile.dev)
• Orchestration: docker-bake.hcl for monorepo multi-target builds
• Not: Building/running containers, debugging runtime issues

---

[1][REQUIREMENTS]

Dictum: Complete requirements prevent generation rework.

Guidance:

• Language -- Language, version, framework, entry point, package manager (pnpm/npm/uv/go mod/maven/gradle)
• Build -- Build commands, Nx target (monorepo), compilation flags, system deps.
• Runtime -- Port(s), env vars, health endpoint, image size constraints, multi-arch (amd64/arm64).

Best-Practices:

• Base images (February 2026): node:24-slim-trixie (pnpm), node:24-alpine3.23 (npm), python:3.14-slim-trixie, golang:1.24-alpine3.23, rust:1.84-slim-trixie, eclipse-temurin:21-jdk-alpine
• Chainguard: cgr.dev/chainguard/node:latest-dev (build) / cgr.dev/chainguard/node:latest (runtime) -- daily CVE rebuilds, zero known vulnerabilities

[REFERENCE]: dockerfile_knowledge.md -- Generation patterns, language substitution, cache mounts.

---

[2][MANDATORY_FEATURES]

Dictum: Every generated Dockerfile includes these features.

Guidance:

• Syntax -- # syntax=docker/dockerfile:1 as first line (enables BuildKit frontend).
• Multi-stage -- Named stages: deps, build, runtime (minimum).
• Security -- Non-root USER 1001:1001, no secrets in ENV/ARG, exec-form ENTRYPOINT.

Best-Practices:

• BuildKit mounts: --mount=type=cache for all pkg managers, --mount=type=secret,id=key,env=VAR for build secrets
• Layer optimization: COPY --link on every COPY, COPY --chmod=555 (no extra RUN chmod layer), heredoc RUN <<EOF for multi-line scripts
• Metadata: OCI labels (org.opencontainers.image.title/source/licenses/revision/created/version), Pulumi-injectable ARGs (GIT_SHA, BUILD_DATE, IMAGE_VERSION)
• Runtime: HEALTHCHECK with --start-interval=2s (exec-form CMD), STOPSIGNAL SIGTERM, non-privileged ports (>1024)

---

[3][PNPM_MONOREPO]

Dictum: This project uses pnpm monorepo with Nx build orchestration.

Guidance:

• Fetch-first -- pnpm fetch --frozen-lockfile downloads to store without installing (maximizes cache hits).
• Deploy -- pnpm deploy --filter=@scope/app --prod /prod/app extracts standalone prod deployment.

Best-Practices:

• corepack: RUN corepack enable (no global pnpm install)
• Offline install: pnpm install --frozen-lockfile --offline --ignore-scripts
• Selective copy: Only needed packages/*/package.json files (not entire workspace)
• Base image: node:24-slim-trixie (glibc, Debian 13 -- not alpine for musl compat)
• Exemplar: apps/api/Dockerfile is the production reference

[REFERENCE]: dockerfile_knowledge.md -- pnpm monorepo pattern, cache mount targets.

---

[4][DELIVERABLES]

Dictum: Output quality measured by image size and security posture.

[INDEX]	[LANGUAGE]	[ESTIMATED_SIZE]
[1]	Node.js (slim-trixie)	80-200 MB
[2]	Python (slim-trixie)	50-250 MB
[3]	Go (distroless)	5-20 MB
[4]	Java (JRE)	200-350 MB

Deliverables: Validated Dockerfile + .dockerignore + validation summary.

Build command with attestations:

docker buildx build \
    --platform linux/amd64,linux/arm64 \
    --sbom=true --provenance=mode=max \
    --build-arg GIT_SHA="$(git rev-parse HEAD)" \
    --build-arg BUILD_DATE="$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
    -t myapp:latest --push .

---

[5][VALIDATION]

Dictum: Five-stage pipeline enforces security and build quality.

Severity classification:

• Critical -- Hardcoded secrets in ENV/ARG, cert bypass flags, no USER directive.
• High -- :latest tag, sudo usage, SSH port (22), no HEALTHCHECK for services.
• Medium -- Missing version pins, cache cleanup, missing OCI labels, no --no-install-recommends.
• Low -- Style (layer count, STOPSIGNAL, heredoc opportunities).

Fix order: Critical first, then high, medium, low. Resolve all critical before moving to high. Max 3 fix-validate cycles.

Tool installation:

[INDEX]	[TOOL]	[INSTALL]	[MIN_VERSION]
[1]	hadolint	Nix-provided on dev machines. VPS: bash .claude/scripts/bootstrap-cli-tools.sh	2.14.0
[2]	Checkov	Nix-provided on dev machines. VPS: bash .claude/scripts/bootstrap-cli-tools.sh	latest (Python 3.9-3.14)

Troubleshooting:

[INDEX]	[ERROR]	[FIX]
[1]	FROM must be first non-comment	Move ARG defining base tag before FROM.
[2]	Unknown instruction	Check spelling (common: RUNS, COPIES, FRUM).
[3]	COPY failed: file not found	Verify path relative to build context, check .dockerignore.
[4]	Hardcoded secrets detected	--mount=type=secret,env=VAR or runtime config.
[5]	COPY --link not recognized	# syntax=docker/dockerfile:1 as first line, Docker 23.0+.
[6]	Heredoc not recognized	# syntax=docker/dockerfile:1 as first line, BuildKit 0.10+.

[REFERENCE]: validation.md -- Security rules, hadolint/Checkov catalogs, BuildKit version matrix.

[VERIFY] Completion:

• Syntax directive: # syntax=docker/dockerfile:1 as first line
• Multi-stage: Named stages with minimal final base
• Security: Non-root USER, no secrets in ENV/ARG, exec-form ENTRYPOINT
• BuildKit: COPY --link, --mount=type=cache, heredoc RUN
• Metadata: OCI labels, Pulumi ARGs, STOPSIGNAL, HEALTHCHECK with --start-interval
• All critical and high validation issues resolved (medium/low: fix or document rationale)

Integration:

• k8s-debug -- Container debugging when builds fail at runtime
• pulumi-k8s-generator -- Pulumi K8s resources with the container image