Dockerfiles — Secure, Multi-Stage Production Images

Production-grade Docker image templates: distroless, non-root, hadolint-clean, multi-stage, and signed-supply-chain ready.

Reference Dockerfiles and best-practice guides for building secure container images that ship to production: small, signed, scanner-friendly, OCI-compliant. Python, Go, JAX, Node.js, TypeScript, Rust, Java, and Zig are covered.

Why these templates

• Multi-stage builds — build toolchains never reach the runtime image. Smaller attack surface, smaller layers.
• Non-root by default — explicit USER nonroot, read-only root filesystem friendly, plays nicely with runAsNonRoot in Kubernetes.
• Pinned bases + locked deps — reproducible builds, scanner-friendly (trivy, grype, scout), and ready for digest-pinning in production.
• Hadolint-clean at the warning threshold — CI enforces it on every push.
• Supply-chain ready — pairs with Cosign signatures, SPDX SBOMs, SLSA provenance, and Kyverno admission control. See the supply-chain guide.

Quick start

# Clone and pick a template.
git clone https://github.com/kssd/dockerfiles.git && cd dockerfiles

# Build the default Python image (Google Distroless, pip).
docker build -t myapp -f dockerfiles/python/Dockerfile.python .

# Run it read-only, no privileges, no network — the hardened way.
docker run --rm \
  --read-only \
  --cap-drop=ALL \
  --security-opt=no-new-privileges \
  --network=none \
  myapp

Need uv, Poetry, AWS Lambda, or a Chainguard base? See the variants below.

Available Dockerfile templates

Python — secure container images for production

Secure Python Docker images on Google Distroless by default, with Chainguard variants for users who want signed/attested daily-rebuilt images. Plus AWS Lambda Python container images and an agent sandbox for LLM-generated code.

Distroless (default — freely pinnable to versioned tags):

• pip + requirements.txt → dockerfiles/python/Dockerfile.python
• uv + pyproject.toml + uv.lock → dockerfiles/python/Dockerfile.uv
• Poetry + poetry.lock → dockerfiles/python/Dockerfile.poetry

Chainguard (signed, attested, daily-rebuilt; free-tier compatible via digest-pinning):

• pip + Chainguard → dockerfiles/python/Dockerfile.python.chainguard
• uv + Chainguard → dockerfiles/python/Dockerfile.uv.chainguard
• Poetry + Chainguard → dockerfiles/python/Dockerfile.poetry.chainguard

Specialized runtimes:

• AWS Lambda container image → dockerfiles/python/Dockerfile.lambda
• Agent sandbox for untrusted LLM-generated code → dockerfiles/python/Dockerfile.sandbox
• VS Code devcontainer (Python 3.12 + uv + Poetry + ruff + mypy + pytest) → dockerfiles/python/Dockerfile.devcontainer

Full documentation: dockerfiles/python/README.md.

Go — statically-linked binaries on Distroless static

Fully-static Go binaries (CGO_ENABLED=0) built with the official golang:*-bookworm image and shipped in gcr.io/distroless/static-debian12:nonroot — no libc, no shell, typically under 10 MB total image size.

Distroless (default — freely pinnable to versioned tags):

• Static binary → dockerfiles/go/Dockerfile.go

Chainguard (signed, attested, daily-rebuilt; free-tier compatible via digest-pinning):

• Chainguard static runtime → dockerfiles/go/Dockerfile.go.chainguard

Specialized runtimes:

• AWS Lambda custom runtime (bootstrap binary on provided:al2023) → dockerfiles/go/Dockerfile.lambda
• VS Code devcontainer (Go 1.23 + golangci-lint + Delve) → dockerfiles/go/Dockerfile.devcontainer

Full documentation: dockerfiles/go/README.md.

JAX — CPU and GPU workloads

Secure JAX Docker images for CPU inference and GPU training. The CPU variant uses Google Distroless; the GPU variant uses python:3.12-slim with jax[cuda12] wheels that bundle the CUDA runtime — no nvidia/cuda base image required. Both variants are non-root and hadolint-clean.

• CPU (distroless, linux/amd64 + linux/arm64) → dockerfiles/jax/Dockerfile.jax.cpu
• GPU / CUDA 12 (linux/amd64, bundled CUDA via jax[cuda12]) → dockerfiles/jax/Dockerfile.jax.cuda
• VS Code devcontainer (JAX CPU + JupyterLab + ruff + mypy + pytest) → dockerfiles/jax/Dockerfile.devcontainer

Full documentation: dockerfiles/jax/README.md.

Node.js — distroless and sandboxed runtimes

Secure Node.js Docker images on Google Distroless by default, with Chainguard variants, an AWS Lambda container image, and an agent sandbox for LLM-generated code.

• Distroless production image → dockerfiles/node/Dockerfile.node
• Chainguard production image → dockerfiles/node/Dockerfile.node.chainguard
• AWS Lambda container image → dockerfiles/node/Dockerfile.lambda
• Agent sandbox for untrusted LLM-generated code → dockerfiles/node/Dockerfile.sandbox
• VS Code devcontainer (Node.js 22 + pnpm + tsx) → dockerfiles/node/Dockerfile.devcontainer

Full documentation: dockerfiles/node/README.md.

TypeScript — compiled to distroless

Multi-stage TypeScript images: a dedicated deps stage for production node_modules, a build stage running tsc, and a Google Distroless runtime with only compiled JS and production deps — no compiler, no dev tooling, no shell.

• Distroless production image → dockerfiles/typescript/Dockerfile.typescript
• Chainguard production image → dockerfiles/typescript/Dockerfile.typescript.chainguard
• VS Code devcontainer (TypeScript + Node.js 22 + pnpm + tsx) → dockerfiles/typescript/Dockerfile.devcontainer

Full documentation: dockerfiles/typescript/README.md.

Rust — cargo-chef dep caching + Distroless cc

Multi-stage Rust images using cargo-chef to cache the dependency-compile layer separately from application source. Ships in Google Distroless cc — glibc and libstdc++ only, no shell, no package manager.

• Distroless production image (GNU) → dockerfiles/rust/Dockerfile.rust
• Chainguard production image → dockerfiles/rust/Dockerfile.rust.chainguard
• VS Code devcontainer (Rust + cargo-edit + cargo-watch + cargo-nextest) → dockerfiles/rust/Dockerfile.devcontainer

Full documentation: dockerfiles/rust/README.md.

Java — Maven/Gradle dep caching + Distroless JRE

Multi-stage Java images supporting both Maven and Gradle via --build-arg BUILD_TOOL. Deps are cached in a dedicated layer before source is copied. Ships in Google Distroless java21 — JRE only, no shell, no package manager. Includes a GraalVM Native Image variant for fast cold starts.

• Distroless JVM image (Maven/Gradle) → dockerfiles/java/Dockerfile.java
• GraalVM Native Image → dockerfiles/java/Dockerfile.java.native
• Chainguard production image → dockerfiles/java/Dockerfile.java.chainguard
• AWS Lambda container image → dockerfiles/java/Dockerfile.lambda
• VS Code devcontainer (Java 21 + Maven + Gradle) → dockerfiles/java/Dockerfile.devcontainer

Full documentation: dockerfiles/java/README.md.

Zig — tarball builder + Distroless static

Multi-stage Zig images that download and SHA-256-verify the official Zig toolchain tarball before use. Produces fully-static binaries (musl libc bundled in the toolchain) that ship in Google Distroless static — the smallest possible runtime: no libc, no shell, no package manager.

• Distroless static image → dockerfiles/zig/Dockerfile.zig
• Chainguard static image → dockerfiles/zig/Dockerfile.zig.chainguard
• VS Code devcontainer (Zig + ZLS + gdb + lldb) → dockerfiles/zig/Dockerfile.devcontainer

Full documentation: dockerfiles/zig/README.md.

Coming soon

Tracked as issues — comment or 👍 to bump priority.

All planned ecosystems are now available. Open an issue to request a new one.

Guides

• Secure software supply chain for Docker images — SBOMs, Cosign signing (keyless and key-based), SLSA v1.0 provenance, and Kyverno admission control. Applies to every ecosystem in this repo.
• Sandboxing LLM-agent-generated code — threat model, the full docker run hardening flag stack with rationale, Kubernetes / Compose / Lambda / Fargate equivalents, and when to graduate to gVisor / Firecracker / Kata.
• Building multi-platform Docker images — local docker buildx setup, QEMU vs native cross-compilation, Go / Rust / Node patterns, GitHub Actions workflows with caching, and common pitfalls.

Repository layout

dockerfiles/
└── <ecosystem>/        # e.g. python/, node/, go/
    ├── Dockerfile.<variant>
    └── README.md
docs/
└── <topic>.md          # cross-ecosystem guides (supply chain, hardening, …)

Tooling

Requires Node.js 20+ (lint tooling only) and hadolint on PATH.

npm install        # installs prettier + markdownlint-cli2
npm run lint       # prettier check + markdownlint + hadolint
npm run format     # prettier --write

GitHub Actions CI runs the same checks on every push and pull request.

Docker for agentic applications

Containerizing AI agents and LLM tool-use breaks the traditional "minimal image" rulebook in interesting ways. The patterns below are why this repo ships an agent sandbox alongside the lean production images.

The "kitchen sink" paradox vs. minimalism

Change: maintain two distinct classes of image.

Traditional best practice says strip every binary not needed at runtime. But AI agents need a broad toolkit (curl, git, build tools, Python libraries, scratch interpreters). The reconciliation is bimodal images:

• Agent Host (Controller) — strict minimalism. Runs the LLM reasoning loop. Zero system tools so a compromised agent cannot pivot.
• Execution Sandbox — a fat, pinned, audited image preloaded with safe tools.

Instead of running apt-get install at runtime (which destroys reproducibility), use a toolbox pattern: images designed to be mounted or called by agents, containing verified versions of every tool the agent might need.

Runtime security for generated code

Change: "running as non-root" is no longer enough.

Agents write and execute their own code. A traditional container assumes the code inside is trusted — but here the container runs untrusted, AI-generated code.

• No network by default — drop network drivers entirely or use --network=none. Whitelist outbound only when justified.
• Ephemeral and read-only — agent workspaces are disposable. --read-only root filesystem with a mounted, wipe-after-task /workspace tmpfs.
• Resource caps — --memory, --cpus, --pids-limit keep runaway agents from taking the host down.

MCP — Dockerfiles as server definitions

Docker is actively integrating with the Model Context Protocol (MCP), the emerging standard that lets agents discover and connect to data sources and tools.

Change: Dockerfiles are becoming "server definitions" for agent tools.

• Standardized entrypoints — images expose MCP server endpoints so agents can discover what an image can do.
• Sidecar patterns — instead of bundling a database client into the agent image, run an MCP gateway alongside it that proxies scoped access.

Traditional vs. agentic, at a glance

Feature	Traditional practice	Agentic practice
Image content	Minimal, only app dependencies	Bimodal — tiny controllers vs. fat toolboxes
Code source	Trusted (human-written)	Untrusted (AI-generated and executed in-loop)
Network	Allow necessary egress	Default deny; strictly scoped per task
Lifecycle	Long-running services	Hyper-ephemeral — spin up, execute, kill

Security

Found a template that materially weakens image security? See SECURITY.md. For supply-chain hardening (signing, SBOMs, provenance, admission control), see the supply-chain guide.

Contributing

PRs welcome — especially for the planned ecosystems above. Read CONTRIBUTING.md first.

License

Apache 2.0. See NOTICE for attribution.

---

_{Keywords: Docker · Dockerfile · Distroless · Chainguard · multi-stage build · hadolint · Python · Go · uv · Poetry · AWS Lambda container image · Cosign · SLSA · SPDX SBOM · Kyverno · MCP · OCI · container security · supply-chain security · non-root container · agent sandbox}