Build Optimized Docker Images with Multi-Stage Dockerfiles

Compiling in a build stage and copying only the artifact into a slim base keeps the runtime tiny.

# Dockerfile
FROM golang:1.22 AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -o app .

FROM gcr.io/distroless/static
COPY --from=build /src/app /app
ENTRYPOINT ["/app"]

Expected output:

$ docker build --check -f Dockerfile . && echo "Dockerfile lints clean"
Dockerfile lints clean

What each line does and why:

• FROM golang:1.22 AS build, starts the build stage from the official Go image and names it build so later instructions can reference it. Pinning the minor version is steadier than latest, but the tag still floats with patch releases, only a digest (golang:1.22@sha256:...) makes a build truly reproducible.
• WORKDIR /src, sets the working directory for subsequent instructions; avoids scattering files across the image root.
• CGO_ENABLED=0, forces a fully static binary with no libc dependency. This is what allows the binary to run on distroless/static, which has no C library at all.
• ENTRYPOINT ["/app"], exec form (JSON array), so the binary runs as PID 1 and receives signals like SIGTERM directly. The shell form (ENTRYPOINT /app) wraps the process in sh -c, which would fail here anyway because distroless has no shell.

The minimal Dockerfile above works, but it wastes the layer cache: COPY . . copies the entire source tree before the build, so any file change, even editing a README, invalidates every layer below it and forces a full re-download of dependencies. The cache-friendly version copies the module files first and downloads dependencies as a separate layer:

Dockerfile, cache-optimized version

# syntax=docker/dockerfile:1
FROM golang:1.22 AS build
WORKDIR /src

# 1. Dependencies change rarely - cache them in their own layer
COPY go.mod go.sum ./
RUN go mod download

# 2. Source code changes often - copy it last
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o app .

FROM gcr.io/distroless/static:nonroot
COPY --from=build /src/app /app
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/app"]

With this ordering, editing main.go only invalidates the layers from COPY . . downward, the go mod download layer is reused and rebuilds drop from minutes to seconds. The extra flags matter too: -trimpath strips local filesystem paths from the binary (reproducibility and information hygiene), and -ldflags="-s -w" omits the symbol and debug tables, shaving roughly 20-30% off the binary size. The runtime stage uses the nonroot tag and USER nonroot:nonroot so the process never runs as root, a cheap, meaningful hardening step.

.dockerignore, keep the build context clean

.git
.gitignore
Dockerfile
.dockerignore
*.md
.env
.env.*
bin/
tmp/
node_modules/

The .dockerignore file controls what gets sent to the Docker daemon as the build context. Without it, COPY . . can silently bake your .git directory, including full history and any secrets ever committed, into an image layer, where it stays even if you delete it in a later layer (earlier layers are immutable and remain in the image). Excluding .env files is the same story: dotenv files are a classic source of leaked credentials in published images.

How to verify: run docker build twice (next step) and watch for CACHED markers beside the go mod download step on the second run. To confirm the context is clean, check the build output line transferring context, it should be kilobytes, not tens of megabytes.

What this teaches: Multi-stage Dockerfiles separate the build toolchain from the runtime; only the artifact ships.

Breaking the command down: DOCKER_BUILDKIT=1 forces the BuildKit backend (redundant on Docker 23+, but harmless and explicit), -t tyf/app:1.0 names and tags the image as tyf/app version 1.0, and the trailing . is the build context, the directory sent to the daemon, filtered through .dockerignore.

On the first run BuildKit pulls both base images and executes every instruction. Use --progress=plain if you want full command output instead of the interactive display, essential in CI logs:

First build (truncated output)

DOCKER_BUILDKIT=1 docker build --progress=plain -t tyf/app:1.0 .

Expected output:

$ docker build -t demo:multi .
[+] Building 12.4s (14/14) FINISHED
 => naming to docker.io/library/demo:multi

Now change one line in main.go and build again. Every step up to COPY . . should report CACHED, and only the compile and export steps re-run:

Tagging discipline matters. tyf/app:1.0 follows the pattern registry-namespace/name:tag. Avoid shipping only latest: mutable tags make rollbacks and incident forensics painful because you cannot tell which build is actually running. A common convention is to tag each build with both a semantic version and the git commit SHA.

How to verify: docker image inspect tyf/app:1.0 --format '{{.Os}}/{{.Architecture}} {{json .Config.Entrypoint}}' should print linux/amd64 ["/app"]. Common mistake: forgetting the trailing . context, which makes Docker read the Dockerfile from stdin and produce a confusing the Dockerfile cannot be empty error.

What this teaches: Layer caching rewards good instruction ordering; put slow, stable steps early and fast, changing steps late.

Numbers make the multi-stage win concrete. First build a naive single-stage version for comparison, the kind of Dockerfile most people write on day one, which ships the entire Go toolchain as the runtime:

Dockerfile.naive, single-stage, for comparison only

FROM golang:1.22
WORKDIR /src
COPY . .
RUN go build -o app .
ENTRYPOINT ["/app"]

Expected output:

$ docker images demo --format '{{.Tag}} {{.Size}}'
single  342MB
multi   48MB

Build both and compare

docker build -f Dockerfile.naive -t tyf/app:naive .
docker images tyf/app

That is roughly a 98% reduction: 892MB down to 12.3MB. Smaller images pull faster, start faster, cost less to store in a registry, and, the security-relevant part, contain drastically fewer packages that can carry CVEs.

To understand where the remaining size lives, inspect the layer history. Each instruction that modified the filesystem contributed a layer:

Inspect image layers

docker history tyf/app:1.0

Reading this bottom-up: the distroless base contributes ~2.2MB (CA certs, tzdata, passwd entries), and the only meaningful addition is the compiled binary at ~10.1MB. Metadata-only instructions like ENTRYPOINT, USER, and EXPOSE cost 0 bytes.

Common mistake: trying to shrink an image by deleting files in a later RUN, e.g. RUN apt-get install ... followed by RUN rm -rf /var/lib/apt/lists in a separate instruction. Layers are additive and immutable: the files still exist in the earlier layer and still count toward the pull size. Cleanup must happen in the same RUN as the install (RUN apt-get update && apt-get install -y foo && rm -rf /var/lib/apt/lists/*), or the data must never enter the image, which is exactly what multi-stage builds achieve for toolchains.

How to verify: confirm the final stage carries no shell or package manager by trying to run one: docker run --rm --entrypoint sh tyf/app:1.0 should fail with an error like exec: "sh": not found. That failure is a feature, an attacker who compromises the process gets no shell and no tooling.

What this teaches: Size comparison makes bloat visible; you cannot optimize what you do not measure.

Trivy inspects the image's package inventory (OS packages plus language dependencies such as Go modules) and matches each component against its vulnerability database. On the very first run it downloads that database (~50MB) to ~/.cache/trivy, so the first scan needs internet access; subsequent runs reuse the cached DB and refresh it periodically.

Scanning the naive single-stage image shows why base image choice dominates your security posture:

The same scan against the multi-stage image tells a very different story:

Distroless images ship almost no packages, so there is almost nothing to be vulnerable. Any findings that do appear against a distroless base are usually in the Go standard library compiled into your binary, and the fix is to rebuild with a patched Go version, which is why pinning and regularly bumping FROM golang:1.22 matters.

To turn the scan into a gate, use --exit-code 1 so Trivy returns non-zero when it finds anything at or above your threshold, the exact behaviour you want blocking a CI pipeline:

Fail the build on CRITICAL findings

trivy image --exit-code 1 --severity CRITICAL tyf/app:1.0
echo "exit code: $?"

Expected output:

$ trivy image --exit-code 1 --severity CRITICAL tyf/app:1.0
tyf/app:1.0 (distroless static)
Total: 0 (CRITICAL: 0)
$ echo "exit code: $?"
exit code: 0

If you need to accept a specific finding temporarily (for example a CVE with no fixed version that you have assessed as not exploitable in your deployment), list it, with a justification comment, in a .trivyignore file at the repo root rather than lowering the severity threshold globally. Ignored CVEs stay visible in version control and reviewable.

Common mistake: scanning the wrong artifact. Scan the final image you actually ship, not the build-stage image or the local Dockerfile. trivy config Dockerfile (misconfiguration scanning) and trivy fs . (dependency scanning) are useful complements, but neither replaces scanning the built image.

How to verify: deliberately scan the naive image and confirm Trivy exits 1 with --exit-code 1, you now know the gate actually fails when it should, not just passes when it should.

What this teaches: Scanning before shipping turns known vulnerabilities into a decision instead of a surprise.