The Go Dockerfile

For Go 1.11 modules, check out this instead.

Warschauerstraße, Berlin

In a devops environment, pushing some code to the repository is not enough. You have to ship it. And the first step is often writing a Dockerfile.

The goals:

  1. The code has to be compiled in a container, to boost the chances my build will be reproducible.
  2. Use dep for fetching the dependencies in case the vendor folder is not committed alongside with the code. NOTE: if vendor/ is in the .gitignore, it should be in the .dockerignore too.
  3. The final image should be as small as possible. Go applications compile to a single binary. We can have images as small as our compiled binary by leveraging the special FROM scratch base image in a multi-stage build.

Here is my base Dockerfile for Go services:

This will work out of the box. But if you plan to use sub-packages, remember to replace “” on line 8 with the actual URI of your repository, in order to provide the compiler with a working import path.

One tricky part is on line 12: the go build step. What is that gibberish?

CGO_ENABLED=0 is an environment variable that tells to the compiler to disable the support for linking C code. As a result, the resulting binary will not be able to depend on the C system libraries. The point is that in a scratch container, there are no system libraries. If we omit this directive, the Docker build will terminate successfully, but the resulting container will crash with funny errors.

standard_init_linux.go:195: exec user process caused “no such file or directory”

installsuffix is probably not necessary in a Docker build, but it looks like it’s a pretty complicated matter. This option is meant to change the name of the folder used to stock the pkg files, by adding a custom suffix. If I get it, specifying a suffix is useful in order to force the compiler to rebuild everything and not rely on the contents of the current pkg folder. Basically, it has a similar meaning to the -a switch.

On line 14, FROM scratch tells Docker to start over, using a new empty base image. The first stage, FROM golang, will be discarded. The final Docker image will only contain this one, which doesn’t even carry an operating system.

COPY --from=builder is the switch for selecting one previous stage to copy a file from. At line 1, we have named the first stage with AS builder. We can now use that name to pick up /app and put it in this new empty stage.

Note that in the last line, the arguments to ENTRYPOINT are given as a JSON array: if instead a string had been passed, Docker would have invoked sh as a tokenizer. And… you have guessed it: there is no sh in a scratch container.

docker: Error response from daemon: OCI runtime create failed: container_linux.go:296: starting container process caused “exec: \”/bin/sh\”: stat /bin/sh: no such file or directory”: unknown.

That’s it! What is your experience with Go Dockerfiles?

EDIT: dep ensure is now executed before COPYing the code from the repo, to allow for locally caching the dependency retrieval independently. Thank you, Reddit folks!

This post originally appeared here.



Test-driven backend engineer. Cryptography consumer. Berlin, Europe.

Love podcasts or audiobooks? Learn on the go with our new app.

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store
Pierre Prinetti

Pierre Prinetti

Test-driven backend engineer. Cryptography consumer. Berlin, Europe.