Docker images for Go services

Why containers, and why Go fits so well

A container image packages your program with everything it needs, so it runs the same on a laptop, in CI and in the cloud. Docker builds and runs images; Kubernetes runs many containers across servers. A Go service is a single static binary, so its image can be almost empty: no language runtime, no package manager, no shell.

A multi-stage Dockerfile

# ---- build stage ----
FROM golang:1.26 AS build
WORKDIR /src

# copy only module files first so the download layer is cached
COPY go.mod go.sum ./
RUN go mod download

COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -trimpath -ldflags="-s -w" -o /out/api .

# ---- final stage ----
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/api /api
USER nonroot:nonroot
EXPOSE 8080
ENTRYPOINT ["/api"]

• FROM golang:1.26 AS build: the official Go image from Docker Hub, named "build" for later.
• Copying go.mod and go.sum first: Docker caches each step, so dependencies are re-downloaded only when those files change, not on every code edit.
• CGO_ENABLED=0: a static binary that needs no C library, so it works on the minimal base.
• distroless/static: Google's minimal base with CA certificates (for HTTPS calls), time-zone data and a non-root user, but no shell or package manager.
• USER nonroot: if an attacker ever breaks in, they are not root inside the container.
• ENTRYPOINT in JSON form: runs the binary directly as process 1, so it receives SIGTERM for graceful shutdown.

Building and running

docker build -t expense-api:1.0.0 .
docker images expense-api          # see how small it is
docker run --rm -p 8080:8080 \
  -e DATABASE_URL="postgres://app:change-me@host.docker.internal:5432/app" \
  expense-api:1.0.0
curl localhost:8080/healthz

scratch versus distroless versus alpine

.dockerignore

.git
bin/
dist/
*.env
.env*
coverage.out

Running Go well in containers

• Listen on 0.0.0.0 (":8080"), not 127.0.0.1, or the port is unreachable from outside the container.
• Log to stdout/stderr (slog to os.Stdout); the platform collects it.
• Handle SIGTERM with graceful shutdown (module 8).
• Memory: Go 1.19+ honours the GOMEMLIMIT environment variable, a soft memory limit for the garbage collector. Setting it a little below the container's memory limit helps avoid out-of-memory kills.
• CPU: since Go 1.25, GOMAXPROCS on Linux follows the container's CPU limit automatically. Older versions used the host's CPU count, which some teams fixed with the go.uber.org/automaxprocs library.