Dockerizing Go

What Docker actually is

A container packages your application together with everything it needs to run — the binary, files, and a minimal OS userland — into one image that runs identically on any machine with a container runtime. Docker is the standard tool for building and running them; you describe the image in a Dockerfile (a recipe of steps), run docker build to produce the image, push it to a registry, and Kubernetes (or docker run) pulls and runs it. New to it? Think “a go build that also packages the OS around your binary.” To learn Docker and Kubernetes themselves (they’re whole topics beyond this Go-focused page), see the official Docker and Kubernetes docs.

The multi-stage build

The standard pattern: compile in a heavy builder stage, then copy only the binary into a minimal final image.

graph LR
SRC["source + go.mod"] --> B["builder stage<br/>golang:1.x (toolchain)"]
B -->|CGO_ENABLED=0 go build| BIN["static binary"]
BIN -->|COPY --from=builder| F["final stage<br/>distroless / scratch"]
F --> IMG["tiny image (~10–20 MB)<br/>no shell · no compiler · non-root"]

# --- builder ---
FROM golang:1.23 AS builder
WORKDIR /src
COPY go.mod go.sum ./
RUN go mod download          # cached layer: deps change rarely
COPY . .
# static, stripped, version-stamped:
RUN CGO_ENABLED=0 go build -ldflags="-s -w -X main.version=$(git rev-parse --short HEAD)" \
    -trimpath -o /app ./cmd/server

# --- final ---
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=builder /app /app
USER nonroot:nonroot         # least privilege
EXPOSE 8080
ENTRYPOINT ["/app"]

Order the COPY go.mod/go mod download before COPY . . so dependency downloads cache across builds. Add a .dockerignore (.git, *_test.go, local artifacts) so the build context stays small.

scratch vs distroless

Two classic “works locally, breaks in the container” traps both come from scratch being empty: a cgo-linked binary won’t run (set CGO_ENABLED=0), and HTTPS calls fail with x509 errors unless CA certs are present (distroless includes them; for scratch, COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/).

See it: read the embedded build info

Go automatically stamps VCS and module info into the binary — readable at runtime, perfect for a /version endpoint that reports exactly which build a pod is running. This runs here:

package main

import (
"fmt"
"runtime/debug"
)

// version can be overridden at build time with:
//   go build -ldflags "-X main.version=$(git rev-parse --short HEAD)"
var version = "dev"

func main() {
fmt.Println("app version:", version)

info, ok := debug.ReadBuildInfo()
if !ok {
	fmt.Println("no build info")
	return
}
fmt.Println("go:", info.GoVersion)
fmt.Println("dependencies:", len(info.Deps))
// In a VCS build, Go also records settings like vcs.revision and vcs.time:
for _, s := range info.Settings {
	if s.Key == "vcs.revision" || s.Key == "GOARCH" {
		fmt.Printf("  %s = %s\n", s.Key, s.Value)
	}
}
}

Expose version on /version, tag the image with the same commit SHA (never rely on :latest in production), and a misbehaving pod can tell you exactly which commit to roll back.

See also

• Why cloud-native Go — why the static binary matters here.
• Kubernetes basics — running the image you just built.
• Supply-chain security — scanning and signing the image.
• The go toolchain (stdlib) — build flags and cross-compilation.

Next: running the image in a cluster — Kubernetes basics.

Related topics