Why use a multi-stage build for Go?

The builder stage holds the full Go toolchain and your source, while the runtime stage ships only the compiled binary. The final image therefore contains no compiler, no source code, and no module cache, which makes it smaller and reduces the attack surface.

When should I use scratch versus alpine?

Use scratch when your binary is fully static — it is the smallest possible image but has no shell, package manager, or CA certificates by default. Use alpine when you need a shell for debugging, package installs, or when CGO is enabled and the binary needs libc.

What does CGO_ENABLED=0 do?

Setting CGO_ENABLED=0 forces Go to use its pure-Go implementations instead of linking against the system C library, producing a fully static binary. That static binary can run on scratch or distroless with no extra shared libraries.

Why does the Dockerfile copy go.mod and go.sum first?

Copying the module files and running go mod download before the rest of your source lets Docker cache the dependency layer. Dependencies are only re-downloaded when go.mod or go.sum changes, so most rebuilds skip that step entirely.

What do the -s and -w ldflags do?

The -s flag strips the symbol table and -w strips DWARF debug information from the binary. Together they shrink the binary by removing data you do not need in production, at the cost of less useful stack traces in a debugger.

Dockerfile Builder for Go

A Dockerfile builder for Go that turns a handful of choices — Go version, module path, build target, and runtime base — into a clean multi-stage Dockerfile that ships the smallest practical image. It is aimed at developers who want a correct, cache-friendly starting point without re-deriving the static-binary build flags every time.

How it works

A Go container is built in two stages. The builder stage starts from the official golang image, copies go.mod and go.sum first so the module download is cached as its own layer, then copies the source and compiles a binary with CGO_ENABLED=0 and -ldflags="-s -w". With CGO disabled the result is a fully static binary that depends on nothing at runtime.

The runtime stage then copies just that binary into a minimal base image. scratch is an empty image — the binary plus a copy of the CA certificate bundle is all that ships. distroless/static adds a non-root user and is a good default when you want something slightly more debuggable than scratch. alpine includes a shell and apk, which you need when CGO is enabled because the binary then links against musl libc.

Tips and notes

If you enable CGO, do not use the scratch runtime — the binary will fail to start because its required C library is missing. Switch to alpine or distroless/base.
Add a .dockerignore containing at least .git and your local build artifacts so the build context stays small and module caching is not invalidated by unrelated files.
A typical static Go service image built this way lands in the 5–15 MB range, versus hundreds of megabytes for a single-stage build on the full golang image.
For reproducible builds, pin the Go version explicitly (for example 1.22) rather than using a floating latest tag.

Dockerfile Builder for Go

Email me this result

How it works

Tips and notes