I've seen this exact scenario play out in countless code reviews. A developer builds a Go service, it works perfectly on their MacBook, they write a Dockerfile, push it to a registry, and then the deployment fails with a cryptic error that makes absolutely no sense given the code.

The mysterious "no such file or directory" error

Imagine you've written a simple API to handle user profiles. You've created a Dockerfile like this:

FROM golang:1.21-alpine
WORKDIR /app
COPY . .
RUN go build -o main .
CMD ["./main"]

You build the image and run it. But instead of your API starting up, you get this:

standard_init_linux.go:211: exec user process caused "no such file or directory"

Wait, what? The file is right there. You literally just ran go build -o main .. You check the container logs, you check the Dockerfile, and everything looks correct. This is one of those Go-specific gotchas that drives people crazy because the error message is lying to you.

The problem isn't that the main binary is missing. The problem is that the binary is dynamically linked to the C library (glibc) on the build machine, but the alpine image uses a different, smaller C library called musl. When the OS tries to run your binary, it looks for the glibc loader, can't find it, and reports that the loader is missing—but it tells you the binary is missing.

Stripping dependencies and disabling CGO

To fix this, we need to tell Go to build a statically linked binary. This means the binary contains everything it needs to run, without relying on the host OS's C libraries. I always do this for containerized Go apps.

Change your build command to this:

RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main .

Here is what's happening:

• CGO_ENABLED=0: This is the magic switch. It tells Go not to use any C code, forcing it to use the pure Go implementation of things like network sockets and DNS.
• GOOS=linux: This ensures that even if you're building on a Mac or Windows machine, the binary is targeted for Linux.
• -a: This forces rebuilding of all packages to ensure everything is statically linked.

Now, the binary is a self-contained unit. It doesn't care if the OS is Alpine, Ubuntu, or even a completely empty image.

Shrinking the image with multi-stage builds

While the fix above works, your image is still huge. You're shipping the entire Go compiler and build toolchain inside your production image. That's like shipping a whole carpentry workshop just to deliver a single chair. It's a security risk (more tools for an attacker) and a waste of bandwidth.

The industry standard is the multi-stage build. We use one image to build the binary, and a second, tiny image to actually run it.

# Stage 1: The Build
FROM golang:1.21-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 GOOS=linux go build -o /app/server .

# Stage 2: The Runtime
FROM scratch
COPY --from=builder /app/server /server
# If your app needs SSL/TLS (HTTPS), you'll need these certificates
COPY --from=builder /etc/ssl/certs/ca-certificates.crt /etc/ssl/certs/
EXPOSE 8080
ENTRYPOINT ["/server"]

I used scratch for the runtime stage. scratch is an empty image. It has nothing—no shell, no package manager, no libraries. Your final image will be just a few megabytes because it contains exactly one thing: your statically compiled Go binary.

Handling environment variables and ports

One final tip: don't hardcode your ports or database strings in your Go code. When you move to containers, you'll be orchestrating these via Kubernetes or Docker Compose, and you'll want to inject configuration via environment variables.

In your Go code, use os.Getenv("PORT"). In your Dockerfile, you can set a default, but it's better to leave it to the environment:

ENV PORT=8080

Remember that EXPOSE in the Dockerfile is mostly documentation. It tells the person running the container which port the app is listening on, but it doesn't actually open the port to the outside world—you still have to map it when you run the container (e.g., docker run -p 8080:8080).

📋 Practical Task

Exercise: Containerizing a Statically Linked Health-Check API

Your goal is to create a production-ready container for a Go application that provides a system health check. This exercise will test your ability to implement a multi-stage build and ensure the binary is statically linked.

Requirements:

• Create a simple Go program that starts an HTTP server on a port defined by an environment variable (default to 8080).
• The server should have one endpoint, /health, which returns a 200 OK status and a JSON body: {"status": "up"}.
• Write a Dockerfile using a multi-stage build:
  • The first stage must use golang:alpine to compile the binary.
  • The second stage must use the scratch image to run the binary.
  • You must use CGO_ENABLED=0 to ensure the binary runs on scratch.
• Ensure the final image size is under 20MB.

Verification:

Build the image and run it. Use curl localhost:8080/health to verify the response. Run docker images to check that your final image is significantly smaller than the build image.