Go Academy · Lesson

Multi-Stage Docker Builds for Go

Builder stage with scratch/alpine final image

Lesson 1 of 413 steps

Multi-Stage Docker Builds for Go is a free Go Academy lesson on CoddyKit. This is lesson 1 of 4. Any 3 lessons of this learning path are free to read in full — after that, CoddyKit PRO unlocks every lesson, plus hands-on practice with a built-in code editor and a 24/7 AI tutor. It is part of the Go Academy learning path, and your progress syncs across the web and the CoddyKit app. The Go Academy course includes 4 lessons in total.

Why multi-stage?

A single-stage build that compiles Go code produces a large image with the full Go toolchain. Multi-stage builds compile in one stage and copy only the binary into a minimal final image.

Basic multi-stage Dockerfile

Build stage compiles the binary; final stage copies it into a minimal base:

FROM golang:1.22-alpine AS build
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -ldflags="-s -w" -o myapp ./cmd/server

FROM scratch
COPY --from=build /app/myapp /myapp
COPY --from=build /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
ENTRYPOINT ["/myapp"]

FROM scratch

A FROM scratch image has nothing — no shell, no OS libraries. The Go binary must be statically linked (CGO_ENABLED=0) and include all needed files explicitly.

FROM distroless

Google's distroless images provide minimal OS libs (CA certs, timezone data) without a shell — safer than scratch for binaries that need libc or TLS certs.

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

FROM alpine for a shell

Use Alpine as the final base when you need a shell for debugging or if the binary uses CGO. Alpine adds ~5MB but includes a shell and package manager.

Layer caching for go.mod

Copy go.mod and go.sum first and run go mod download before copying source code. This layer is cached until dependencies change, speeding up rebuilds.

COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build ...

-ldflags="-s -w"

-s strips the symbol table; -w strips DWARF debug information. Together they reduce binary size by 30-50% with no runtime impact.

Build arguments

Use ARG to inject version info at build time:

ARG VERSION=dev
RUN go build -ldflags="-X main.version=${VERSION}" -o myapp .

Non-root user

Run the binary as a non-root user for security. Add a user in a base image or use distroless's nonroot tag:

FROM gcr.io/distroless/static-debian12:nonroot

Final image size

A typical Go binary from scratch is 5-20 MB. Alpine adds ~5MB. A full golang image is ~800MB. Multi-stage builds reduce attack surface and image pull time significantly.

.dockerignore

Add a .dockerignore to exclude files from the build context: vendor/, .git/, *.test, *.prof. This speeds up the Docker build and prevents sensitive files from being included.

.git
vendor
*.test
*.prof
.env

Quick Check

Why must CGO_ENABLED=0 be set when building a Go binary for a FROM scratch Docker image?

Answer it in the interactive lesson

Recap: Multi-Stage Docker Builds

Key points:

Build stage: golang image; final stage: scratch/distroless/alpine
CGO_ENABLED=0 for static binary (required for scratch)
Copy go.mod first for layer caching; -ldflags="-s -w" for smaller binary
.dockerignore to exclude .git, vendor, test files

Free to start

Learn Go with an AI tutor — free

Write and run real code in your browser, get instant help from a 24/7 AI tutor, and pick up where you left off on the web or in the app.

Courses: 51
Lessons: 203

Start learning free View the full course

Frequently Asked Questions

Is the “Multi-Stage Docker Builds for Go” lesson free?

Yes — any 3 lessons of the Go Academy learning path, including “Multi-Stage Docker Builds for Go”, are free to read in full here on the web. After that, CoddyKit PRO unlocks every lesson, plus interactive practice with a built-in code editor and a 24/7 AI tutor. The Go Academy course includes 4 lessons in total.

What will I learn in “Multi-Stage Docker Builds for Go”?

Builder stage with scratch/alpine final image You practise Go Academy with hands-on code you run directly in the browser, and a 24/7 AI tutor answers your questions as you work through the lesson.

Do I need any experience to start Go Academy?

No prior experience is required. Go Academy on CoddyKit is structured for beginners through advanced learners, so you can start here or from the beginning and move at your own pace. This is lesson 1 of 4.

How long does the “Multi-Stage Docker Builds for Go” lesson take?

Most CoddyKit lessons take about 5–10 minutes. Each one is bite-sized and interactive, so you make steady progress and pick up exactly where you left off across the web and the app.

Can I write and run code in this Go Academy lesson?

Yes. Every Go Academy lesson includes a built-in code editor, so you write and run real code right in your browser and get instant AI feedback — no local setup required.

All lessons in this course

← Back to Go Academy