Dockerizing Go applications: what developers should know

Introduction

Go binaries are wonderfully small and self-contained, but shipping them in a bloated Docker image defeats the purpose. Dockerizing Go applications: what developers should know starts with understanding that a 15 MB binary should never live in a 900 MB image when a few smart choices can reduce that to under 20 MB total. We've built APIs across e-commerce, trading, and SaaS platforms where container image size directly impacts deployment speed, registry costs, and security surface area—and the wins compound quickly.

In this guide, we'll walk through the real practices that separate production Go deployments from amateur hour: multi-stage builds to strip compilation tooling, static binaries for portability across different Linux distributions, intelligent layer caching to keep build times reasonable, and running containers as non-root users because security defaults matter.

Multi-stage builds: compile separately, run lean

The core insight is simple: you need a Go compiler to build your binary, but you don't need one to run it. Multi-stage Docker builds let you compile in a heavy image, then copy only the final artifact into a minimal runtime image.

Here's the pattern we use in production:

FROM golang:1.23 AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -o /app ./cmd/api

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

The first stage, tagged AS build, uses the official Go image. We set the working directory, copy our entire source tree, and compile a statically-linked binary (we'll explain CGO_ENABLED=0 in a moment). The output goes to /app in that container's filesystem.

The second stage starts fresh from gcr.io/distroless/static, a Google-maintained image containing only the bare essentials: libc and a shell, totaling around 2–5 MB. We copy the compiled binary from the build stage and set it as the entrypoint. The final image is just your binary plus the minimal runtime—no Go toolchain, no source code, no package manager.

On a recent trading system API we worked on, this approach dropped the image from 850 MB to 18 MB. Registry storage and pull times fell dramatically. More importantly, the attack surface shrunk: there's no shell history, no package manager, no dev tools an attacker could pivot through.

If you need absolutely minimal images and can tolerate no shell for debugging, use FROM scratch instead. This is a zero-byte base—your binary is literally the entire image. It's genuinely useful for extremely resource-constrained environments, though we typically prefer distroless for the tiny bit of debugging flexibility it provides.

Static binaries: portability across Linux variants

By default, Go tries to link against system libc dynamically. This works fine on your laptop but can fail mysteriously when you deploy to a different Linux distribution or Alpine-based images. The solution is CGO_ENABLED=0, which tells Go to compile a statically-linked binary that carries all its dependencies internally.

In our earlier Dockerfile snippet, we included it:

RUN CGO_ENABLED=0 go build -o /app ./cmd/api

Always set this in your build stage. The performance impact is negligible for typical API workloads. Yes, the binary gets slightly larger (you're embedding libc), but we're still talking single-digit megabytes for most services.

Real-world impact: A ride-hailing platform we worked on had a nightmarish incident where the same binary ran fine on the build machine but crashed immediately on production runners. Root cause was dynamic libc linking—Alpine uses musl, Ubuntu uses glibc, and the binary couldn't find what it needed. Static linking solved it completely. Now the same binary runs anywhere.

If you're using cgo—calling C libraries directly—you'll need to think harder. Statically linking C dependencies is possible but messier; it often requires building in a matching environment (e.g., Alpine in Docker if your target is Alpine). For most Go services, avoiding cgo entirely is the cleaner path. Standard library packages like net, crypto, and os work great without it.

Cache modules intelligently: Docker layer strategy

Docker builds are layered. Each instruction creates a new layer; if something changes, Docker rebuilds from that point onward. This matters for build speed.

A naive Dockerfile looks like this:

FROM golang:1.23 AS build
WORKDIR /src
COPY . .
RUN CGO_ENABLED=0 go build -o /app ./cmd/api

Problem: every time any source file changes, Docker invalidates the cache and re-runs go mod download, which fetches all your dependencies again. If you have 50 dependencies and a slow connection, this adds minutes to every build.

The fix: copy dependency files first, download dependencies in their own layer, then copy source code:

FROM golang:1.23 AS build
WORKDIR /src

# Cache modules layer
COPY go.mod go.sum ./
RUN go mod download

# Source changes invalidate only the build step
COPY . .
RUN CGO_ENABLED=0 go build -o /app ./cmd/api

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

Now when you tweak a handler or fix a bug, Docker skips the go mod download step because go.mod and go.sum haven't changed. On a typical service with 30–100 dependencies, this saves 30–60 seconds per build.

We've seen teams save hundreds of hours per year with this simple layer ordering. In CI/CD pipelines running dozens of builds per day, the compounding effect is significant.

Non-root users: distroless security defaults

Distroless images ship with a non-root user already configured. When you run docker run without specifying a user, the container executes as this unprivileged account. This is genuinely valuable: if your application has a vulnerability and an attacker gains code execution, they're sandboxed as a restricted user rather than root.

On a CRM platform we secured, a compromised dependency could read files but couldn't modify system configuration or escape the container. Being non-root prevented lateral movement.

If you need to run as a specific user or add one yourself (e.g., you're using a custom base image), add it explicitly:

FROM alpine:3.18
RUN addgroup -g 1000 app && adduser -D -u 1000 -G app app
USER app
COPY --from=build /app /app
ENTRYPOINT ["/app"]

The USER directive is small but critical. Always include it. Omitting it means your container runs as root by default, which is a security anti-pattern.

Distroless makes this trivial—you don't need to add users yourself because they're already there. That's another reason we prefer distroless in production APIs.

Common mistakes

• Forgetting CGO_ENABLED=0. Your binary works locally then crashes in production on a different Linux variant. Test your Dockerfile on a clean machine to catch this early.
• Not layer-caching modules. Your builds take 2–3 minutes because dependencies re-download on every change. Separate go.mod copy and download from source copy.
• Using ubuntu or alpine without a multi-stage build. You'll end up with 500+ MB images containing Go toolchain, build artifacts, and source code. This is rarely intentional.
• Running as root. Distroless runs as non-root by default, but if you build a custom image, remember the USER directive. Skipping it is a preventable security gap.
• Copying entire directories carelessly. COPY . . includes everything—vendor, .git, test fixtures, credentials in env files. Use a .dockerignore file to exclude what shouldn't be in the image.

Key takeaways

• Multi-stage builds separate compile-time dependencies from runtime requirements, shrinking final images from 800+ MB to 15–30 MB.
• Set CGO_ENABLED=0 to ensure your binary runs on any Linux distribution without dynamic libc issues.
• Layer your Dockerfile so go.mod and go.sum are copied and cached separately, saving 30–60 seconds on builds where only source code changes.
• Prefer distroless base images: they're tiny, secure by default (non-root user), and carry minimal attack surface.
• Always set a USER directive if you're not using distroless; running as root in production is a security anti-pattern.
• Test your Dockerfile on a clean machine to catch platform-specific issues before they reach production.