BuildKit, multi-stage builds and CI caching
Multi-stage builds
Use one stage with compilers and build tools, and copy only the artifact into a minimal runtime stage:
# syntax=docker/dockerfile:1
FROM maven:3.9-eclipse-temurin-21 AS build
WORKDIR /src
COPY pom.xml .
RUN --mount=type=cache,target=/root/.m2 mvn -B dependency:go-offline
COPY src ./src
RUN --mount=type=cache,target=/root/.m2 mvn -B package -DskipTests
FROM eclipse-temurin:21-jre-alpine AS runtime
WORKDIR /app
COPY --from=build /src/target/orders.jar app.jar
RUN addgroup -S app && adduser -S app -G app
USER app
ENTRYPOINT ["java", "-XX:MaxRAMPercentage=75", "-jar", "app.jar"]
Results: no JDK, Maven, or source code in the final image — smaller (often 70–90% smaller), faster to pull, fewer CVEs. Go and Rust can go further with static binaries on scratch or gcr.io/distroless/static.
You can build a specific stage with --target build (e.g. to run tests in CI).
BuildKit features worth knowing
BuildKit is the default builder in modern Docker (docker buildx build). It builds independent stages in parallel, skips unused stages, and adds:
- Cache mounts —
RUN --mount=type=cache,target=/root/.npm npm cikeeps a package cache between builds without baking it into layers. - Secret mounts — the secret is available only during that
RUNand never stored in a layer:
RUN --mount=type=secret,id=npmrc,target=/root/.npmrc npm ci
docker buildx build --secret id=npmrc,src=$HOME/.npmrc -t app .
- SSH forwarding —
RUN --mount=type=ssh git clone [email protected]:acme/private.gitwith--ssh default. - Remote cache for CI, where each build starts on a fresh agent:
docker buildx build \
--cache-from type=registry,ref=$ECR/orders:buildcache \
--cache-to type=registry,ref=$ECR/orders:buildcache,mode=max \
-t $ECR/orders:$GIT_SHA --push .
(GitHub Actions also has type=gha.) mode=max caches intermediate stages too.
- Multi-architecture builds — build amd64 and arm64 in one manifest list:
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 -t $ECR/orders:$GIT_SHA --push .
Cross-builds use QEMU emulation (slow for compiled languages) or native builders per architecture.
Never put secrets in images
Anything passed via ARG, ENV, or COPY ends up in layers or image config, readable by anyone who can pull the image (docker history, extracting layers). Even a COPY id_rsa followed by RUN rm id_rsa leaks — the file is in the earlier layer. Use secret mounts at build time and inject runtime secrets from Secrets Manager / Kubernetes Secrets / External Secrets.
Reproducible builds
- Pin base images by version and ideally digest (
FROM python:3.12-slim@sha256:...), updated deliberately by Renovate/Dependabot. - Use lockfiles (
package-lock.json,poetry.lock) andnpm cirather thannpm install. - Tag every image with the git commit SHA (plus semver for releases) so an image maps to exactly one source revision.
- Add OCI labels (
org.opencontainers.image.revision,.source) for traceability.