Building images: Dockerfiles, the layer cache and multi-stage builds

The app

Until now you ran images other people built. Now you'll package your own: a small Go API with one endpoint.

// main.go
package main

import (
	"fmt"
	"log"
	"net/http"
	"os"
)

func main() {
	version := os.Getenv("APP_VERSION")
	http.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
		fmt.Fprintf(w, "{\"status\":\"ok\",\"version\":%q}\n", version)
	})
	log.Println("price-api listening on :8080")
	log.Fatal(http.ListenAndServe(":8080", nil))
}

Next to it, go.mod (module price-api and go 1.27). The same ideas apply to a Node, Python or Java app; only the build commands change.

A first Dockerfile

A Dockerfile is the recipe. Each instruction is one step, and most steps produce a layer:

FROM golang:1.27-alpine        # start from an image with Go installed
WORKDIR /src                   # cd into /src (created if missing)
COPY . .                       # copy the build context into /src
RUN go build -o /price-api .   # run a command at build time
CMD ["/price-api"]             # the default command when a container starts

$ docker build -t price-api:single -f Dockerfile.single .
$ docker run -d --name api -p 8090:8080 -e APP_VERSION=1.0.0 price-api:single
$ curl -s localhost:8090/health
{"status":"ok","version":"1.0.0"}

The . at the end is the build context: the folder Docker sends to the builder, and the only files COPY can see. The instructions you'll use most:

Write ENTRYPOINT and CMD in the JSON exec form, ["/price-api"]. The shell form (CMD /price-api) wraps your app in /bin/sh -c, so the shell becomes PID 1 and may not pass docker stop's SIGTERM on (the Linux course's Signals lesson explains why that matters).

.dockerignore

COPY . . copies everything in the context. Without a .dockerignore, that includes .git, .env files with secrets, node_modules and editor junk, and any change to them breaks the cache:

# .dockerignore
.git
.env
*.md
Dockerfile*

The layer cache

Every step is cached by its instruction and its inputs. On the next build Docker reuses a step only if it, and every step above it, is unchanged. The moment one step changes, it and everything below it run again:

⤢ View

Same Dockerfile, three builds. What changed decides where the rebuild starts.© Animation: DevOps Academy

Close

So the order matters. Copy the dependency list first and download, then copy your code:

COPY go.mod ./                 # changes rarely (go.sum too, once you have dependencies)
RUN go mod download            # cached until go.mod changes
COPY . .                       # changes on every commit
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /out/price-api .

For Node that's COPY package.json package-lock.json ./ then RUN npm ci; for Python, COPY requirements.txt . then RUN pip install -r requirements.txt. Here's a real rebuild after changing one line of main.go:

⤢ View

Steps 2 to 4 are CACHED. Only the copy of the code and the compile run again.© Screenshot: DevOps Academy

Close

The compile still takes over two minutes on this machine, because Go's own build cache is thrown away with each layer. A cache mount keeps it between builds, outside the image:

RUN --mount=type=cache,target=/root/.cache/go-build \
    CGO_ENABLED=0 go build -ldflags="-s -w" -o /out/price-api .

Package managers have the same trick (/root/.npm, /root/.cache/pip). The mount never becomes part of the image.

Multi-stage builds

The first image works, but look at it:

$ docker images price-api
IMAGE              ID             DISK USAGE   CONTENT SIZE
price-api:multi    034074b20fb9       14.6MB         3.24MB
price-api:single   367778fc7a08        508MB          102MB
$ docker run --rm price-api:single du -sh /usr/local/go
282.1M	/usr/local/go
$ docker run --rm price-api:single id
uid=0(root) gid=0(root) groups=0(root),…

508MB, of which 282MB is the Go compiler, plus your source code, a shell and package manager, all running as root. Production needs one file: the binary. A multi-stage build compiles in one stage and copies only the result into a clean one:

# syntax=docker/dockerfile:1

# Stage 1: build with the full Go toolchain
FROM golang:1.27-alpine AS build
WORKDIR /src
COPY go.mod ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o /out/price-api .

# Stage 2: ship only the binary
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/price-api /price-api
USER nonroot
EXPOSE 8080
ENTRYPOINT ["/price-api"]

Only the last stage becomes the image. COPY --from=build reaches back into the build stage for the binary; the compiler, source and module cache stay behind. CGO_ENABLED=0 makes a static binary that needs no C library, and -ldflags="-s -w" strips debug symbols. The result is the 14.6MB image above.

docker build --target build . stops after a named stage: handy for running tests in the build stage (lesson 13).

Smaller, safer images

The distroless image has no shell at all, which also means an attacker who gets in has no shell to use:

$ docker image inspect price-api:multi --format '{{.Config.User}}'
nonroot
$ docker run --rm --entrypoint sh price-api:multi
docker: Error response from daemon: … exec: "sh": executable file not found in $PATH

docker history price-api:multi lists each layer and its size: the only big one is your 5.86MB binary.

Image metadata and repeatable builds

ENTRYPOINT is the executable; CMD supplies default arguments. ARG is build-time input, ENV is a runtime default, and neither is a secret store. HEALTHCHECK reports process health. Keep .dockerignore beside the Dockerfile so credentials and build output never enter the context.

LABEL org.opencontainers.image.source="https://example.invalid/academy"
ARG BUILD_VERSION=dev
ENV APP_VERSION=$BUILD_VERSION
HEALTHCHECK --interval=30s CMD wget -qO- http://127.0.0.1:8080/health || exit 1
ENTRYPOINT ["/app/server"]
CMD ["--listen=:8080"]

BuildKit cache mounts speed installs, secret mounts keep a secret out of layers, and buildx can publish multiple architectures:

$ printf '.git\n.env\nnode_modules\n' > .dockerignore
$ docker buildx build --platform linux/amd64,linux/arm64 --cache-to type=local,dest=.buildx-cache \
    --cache-from type=local,src=.buildx-cache -t example/app:dev .

$ docker build -t price-api:single -f Dockerfile.single .
$ docker build -t price-api:multi .
$ docker images price-api --format '{{.Tag}} {{.Size}}'
multi 14.6MB
single 508MB
$ docker run -d --name api -p 8090:8080 -e APP_VERSION=1.0.0 price-api:multi
$ curl -s localhost:8090/health
{"status":"ok","version":"1.0.0"}
$ docker image inspect price-api:multi --format '{{.Config.User}}'
nonroot
$ sed -i 's/listening/now listening/' main.go && docker build -t price-api:multi . 2>&1 | grep CACHED
$ docker rm -f api