One of the key announcements at Dockercon 2017 was the launch of multi-stage builds. It is available in Docker version 17.05 onwards and is one of most exciting features coming out. In this post, we will do a quick demo of the feature and then discuss the details.

Setup

One of the quickest ways to get our hands dirty with this feature is to sign up for a Docker lab and add a new instance. This will spin up a new docker-in-docker container, which can be used for our experimentation. Before going ahead, let's ensure the Docker version is correct by running the command docker version.

If the version of docker server is less than 17.05, perform the following steps:

• To download the Docker daemon 17.05-dev, run the following command:

curl -L https://master.dockerproject.org/linux/amd64/dockerd-17.05.0-dev -o dockerd

• Run the following command to overwrite the existing dockerd:

mv ./dockerd /usr/local/bin/dockerd && chmod +x /usr/local/bin/dockerd

• Kill the dockerd process by running ps -a and run the following command to start the docker daemon again

nohup /usr/local/bin/dockerd &

• Verify the Docker daemon version by running docker version

Building the Image the Old Way

Clone the git repo of this sample go-lang application and cd to the code directory. We will now build an image of the demo app via the default go-lang parent as a base image using the command docker build -t demo-go-app:1.0 ..One of the key things to notice here is the content of Dockerfile, which is simply the golang image’s on-build tag:

FROM golang:1.6.3-onbuild

Once the image is built, verify the image size using the command docker images. The image is about 756MB.

The World of Multi-Stage Builds

Now check out the multi-stage branch of the same repo. One of the first things you will notice is a starkly different Dockerfile:

FROM golang:1.6.3-alpine
RUN mkdir /app
ADD . /app/
WORKDIR /app
RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o main .
FROM alpine:latest
WORKDIR /root/
COPY --from=0 /app/main .
CMD ["/root/main"]

There are two FROM directives in this file, which was not allowed before. With multi-stage builds, a Dockerfile allows multiple FROM directives, and the image is created via the last FROM directive of the Dockerfile.

The next interesting statement is COPY –from=0 /app/main .. This takes the file /app/main from the previous stage and copies it to the WORKDIR. This basically copies the compiled go binary created from the previous stage.

Now let's run the Docker build command docker build -t demo-go-app:2.0 . and verify the size by running docker images again:

The image size is around 13.1 MB, which is a fraction of the older size (756MB).

A Word of Caution

If the build product is a compiled binary, a consistent platform has to be maintained. A binary compiled for Linux will not work on Alpine. For example, below are the file attributes of the above application when it is built via golang:1.6.3-onbuild:

root@44fee7671056:/go/src/app# file /go/bin/app
/go/bin/app: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), dynamically linked, interpreter /lib64/ld-linux-x86-64.so.2, not stripped

Looking at the same application when compiled via golang:1.6.3-alpine:

$ docker exec -it c7a6afccf5509c2032444f14906cf17267994a3191e5d368fad9cff679797377 file /root/main
/root/main: ELF 64-bit LSB executable, x86-64, version 1 (SYSV), statically linked, not stripped

If the application compiled via golang:1.6.3-onubild gets copied to an Alpine container, the application wont execute and will give an error, as below:

$ ./app
bash: ./app: cannot execute binary file: Exec format error

This is why the Dockerfile used in multi-stage build of the demo application is using golang:1.6.3-alpine as its base image, instead of golang:1.6.3-on-build.

Why Is the Multi-Stage Image so Small?

The main reason for the image being so small is that its parent image itself is very small. While the golang:1.6.3 image was about 750MB, the Alpine image was a mere 3.99 MB. Why Alpine images so small, and their other advantages, are explained in detail here. The golang base image contains golang installation + Python installation and many supporting modules, which are not really needed once the compiled application is ready.

Consider another approach, where you would use Alpine as a base image and create an application over it. This would mean adding every little dependency by hand to your Dockerfile and adding more steps to image creation, which is certainly not desirable.

A third option is to use the Alpine distribution of golang, such as golang:1.6.3-alpine. This also creates an image of around 300 MB, since the OS is barebones but all golang dependencies and support modules are present.

Multi-stage builds solve the above problems by giving the developer the flexibility to use bloated base images to create an executable/JAR file. Once the application is compiled, the remaining bloatware is not needed and the application itself can be easily injected into a minimal image, giving all the advantages of a small image size.