Docker multistage go alpine

When to use

• Deploying a Go backend service via Docker.
• You want a small, fast-to-pull image without shipping the Go toolchain in production.
• You have multiple binaries from the same module (server, CLI, migrator).

Steps

1. Builder stage — full Go toolchain, layer-caches deps before source:

   FROM golang:1.26-alpine AS builder
   RUN apk add --no-cache git
   WORKDIR /src
   COPY server/go.mod server/go.sum ./server/
   RUN cd server && go mod download
   COPY server/ ./server/
   ARG VERSION=dev
   ARG COMMIT=unknown
   RUN cd server && CGO_ENABLED=0 go build -ldflags "-s -w -X main.version=${VERSION} -X main.commit=${COMMIT}" -o bin/server ./cmd/server
   RUN cd server && CGO_ENABLED=0 go build -ldflags "-s -w" -o bin/migrate ./cmd/migrate
   

   • CGO_ENABLED=0 → static binary, runs on plain alpine.
   • -s -w → strip symbol and DWARF tables (~30% smaller).
   • -X main.version → inject version/commit at link time.
2. Runtime stage — minimal alpine with only what the binary needs at runtime:

   FROM alpine:3.21
   RUN apk add --no-cache ca-certificates tzdata
   WORKDIR /app
   COPY --from=builder /src/server/bin/server .
   COPY --from=builder /src/server/bin/migrate .
   COPY server/migrations/ ./migrations/
   COPY docker/entrypoint.sh .
   RUN sed -i 's/\r$//' entrypoint.sh && chmod +x entrypoint.sh
   EXPOSE 8080
   ENTRYPOINT ["./entrypoint.sh"]
   

   • ca-certificates for HTTPS, tzdata for time-zone-aware scheduling.
   • sed -i 's/\r$//' on entrypoint handles Windows checkouts with CRLF.
3. Pass version metadata at build time:

   docker build --build-arg VERSION=$(git describe --tags) --build-arg COMMIT=$(git rev-parse --short HEAD) -t app .
   

Example

Final image size for a mid-size Go service: ~30-50 MB (vs ~800 MB for a naive single-stage with the toolchain).

Caveats

• If your code uses cgo (e.g. sqlite), drop CGO_ENABLED=0 and switch runtime to alpine:3.21 → add libc6-compat or run on gcr.io/distroless/cc.
• Multiple binaries in the same image bloat it; if you deploy them as separate containers, split into separate Dockerfiles.