Opscraft
Docker · Lesson 4 of 11 · 4 min read

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.

Enlarge diagramSTAGE 1: BUILDSTAGE 2: RUNTIME IMAGEmaven + JDK + source codemvn package → orders.jarJRE only, non-root userorders.jar≈ 800 MB, thrown away≈ 200 MB, shippedCOPY --from=build
Figure 1. A multi-stage build: compile in a big image with all the tools, then copy only the result into a small runtime image.
Swipe sideways to see all of it, or tap to open it full screen.

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 ci keeps a package cache between builds without baking it into layers.
  • Secret mounts — the secret is available only during that RUN and 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.git with --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.

Enlarge diagramLeaksSafeCOPY id_rsa, then RUN rm id_rsaENV DB_PASSWORD=…ARG NPM_TOKEN (visible in history)RUN --mount=type=secret at build timeSSH forwarding with --sshRuntime secrets from Secrets Manager orKubernetes
Figure 2. Never bake secrets into images. Anything copied, set as ENV or passed as ARG can be read from the layers or the image config.
Swipe sideways to see all of it, or tap to open it full screen.

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) and npm ci rather than npm 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.