How to Create the Smallest Docker Image for Your Golang App

in the container ecosystem, there's a lot of chatter about security and best practices to build the ultimate container image. the main goal is to create an image that is slim, secure, speedy, stable, and set.

i didn't have time to create a slim image, so i created a fat one instead.

shortcuts are evil and we need to aim for slim images instead of fat ones, which cause problems (security, performance, maintenance) in the long run.

let's get started!

scratch for the win!

the first step is to understand how to create a docker image with no base like ubuntu or alpine , for example. we want the bare minimum. the goal is to isolate our process with no dependencies or stuff we don't need. the scratch base image is your answer.

you can use docker’s reserved, minimal image, scratch , as a starting point for building containers. using the scratch image signals to the build process that you want the next command in the dockerfile to be the first filesystem layer in your image. each docker image references a list of read-only layers that represent filesystem differences. layers are stacked on top of each other to form a base for a container’s root filesystem.

behold!

the smallest possible docker image for an executable. the executable should be a static build.

a static build is a compiled version of a program that has been statically linked against libraries. in computer science, linking means taking one or more objects generated by compilers and assembling them into a single executable program.

steps to take:

• download the smallest hello world app in the world.
• create a dockerfile:

# start from scratch
from scratch

# copy our static linked executable
copy helloworld helloworld

# tell how to run this container 
cmd ["./helloworld"]  

• build the image $ docker build . -t helloworld:smallest

sending build context to docker daemon 3.072 kb  
step 1/3 : from scratch  
 --->
step 2/3 : copy myapp myapp  
 ---> using cache
 ---> c3e978eab3c8
step 3/3 : cmd ./myapp  
 ---> using cache
 ---> cc6eb6cc3479
successfully built cc6eb6cc3479  

• run the container $ docker run helloworld:smallest

hi world  

• check the size of each layer $ docker history helloworld:smallest

image               created             created by                                      size                comment  
cc6eb6cc3479        9 minutes ago       /bin/sh -c #(nop)  cmd ["./myapp"]              0 b  
c3e978eab3c8        11 minutes ago      /bin/sh -c #(nop) copy file:863b4441410c89...   142 b  

a docker image of 142 bytes. eat that!

the two-stage rocket build

the 1 million dollar question is, "how do we build our golang application, get the executable, and put it inside a container in one command?"

unfortunately, you can't do this in an automated fashion using the standard docker tooling. luckily, we created a project called habitus to automate this process.

basically, we need two stages. build the artefact using $ go build and copy the executable into our final image. let's create both stages using dockerfiles and glue them together with the habitus rocket!

let's start with a simple http service written in golang:

main.go

package main

import (  
"fmt"
"net/http"
)

func handler(w http.responsewriter, r *http.request) {  
    fmt.fprintf(w, "hello world!")
}

func main() {  
    http.handlefunc("/", handler)
    fmt.println("simple helloworld server is running on port 8080")
    http.listenandserve(":8080", nil)
}

we need to build the executable first before we can run it as an isolated process using containers. enter stage #1!

stage #1

the responsibility of this stage is to build an image that can build your golang executable and extract the artifact.

dockerfile.builder

# start a golang base image, version 1.8
from golang:1.8

#switch to our app directory
run mkdir -p /go/src/helloworld  
workdir /go/src/helloworld

#copy the source files
copy main.go /go/src/helloworld

#disable crosscompiling 
env cgo_enabled=0

#compile linux only
env goos=linux

#build the binary with debug information removed
run go build  -ldflags '-w -s' -a -installsuffix cgo -o helloworld  

to build it manually, run this command to build it:
$ docker build -f dockerfile.builde -t builder:latest .

copy the compiled artifact to your local disk
$ docker container cp [id_of_container]:/go/src/helloworld/helloworld helloworld

stage #2

the responsibility of this stage is to copy the artifact into the smallest possible image.

dockerfile.production

# start with a scratch (no layers)
from scratch

# copy our static linked library
copy helloworld helloworld

# tell we are exposing our service on port 8080
expose 8080

# run it!
cmd ["./helloworld"]  

to build it manually, run this command:
$ docker build -f dockerfile.production -t helloworld:latest .

building your rocket to create the smallest possible docker image

with habitus , you need a build.yml to tell which steps are necessary for the docker build flow. habitus gives you the power to handle a complex build flow without getting into bash hell.

build.yml

build:  
  version: 2016-03-14 # version of the build schema.
  steps:
    builder:
      name: builder
      dockerfile: dockerfile.builder
      artifacts:
        - /go/src/helloworld/helloworld
    production:
      name: helloworld:latest
      dockerfile: dockerfile.production
      depends_on:
        - builder

build everything in one command! easy as it gets.

$ habitus

017/04/05 10:14:01  using '/users/danielvangils/desktop/cloud 66/projects/go_projects/src/github.com/cloud66/helloworld/build.yml' as build file  
2017/04/05 10:14:01  collecting artifact information  
2017/04/05 10:14:01  building 2 steps  
2017/04/05 10:14:01  step 0 - builder: builder  
2017/04/05 10:14:01  step 1 - production: helloworld:latest  
2017/04/05 10:14:01  parallel build for builder  
2017/04/05 10:14:01  building builder  
2017/04/05 10:14:01  parsing and converting 'dockerfile.builder'  
2017/04/05 10:14:01  writing the new dockerfile into dockerfile.builder.generated  
2017/04/05 10:14:01  building the builder image from dockerfile.builder.generated  
step 1/7 : from golang:1.8  
 ---> 9ad50708c1cb
...
step 7/7 : run go build  -ldflags '-w -s' -a -installsuffix cgo -o helloworld  
 ---> running in 93778ba1c98c
 ---> b9736e1bf07c
removing intermediate container 93778ba1c98c  
successfully built b9736e1bf07c  
2017/04/05 10:14:12  building container based on the image  
2017/04/05 10:14:12  starting container 3278c37f63092f70e3ef157268d3bc770f0333b550c9a10ec0527940dc677833 to fetch artifact permissions  
2017/04/05 10:14:13  permissions for /go/src/helloworld/helloworld is 755  
2017/04/05 10:14:13  stopping the container 3278c37f63092f70e3ef157268d3bc770f0333b550c9a10ec0527940dc677833  
2017/04/05 10:14:14  copying artifacts from 3278c37f63092f70e3ef157268d3bc770f0333b550c9a10ec0527940dc677833  
2017/04/05 10:14:14  copying from /go/src/helloworld/helloworld to /users/danielvangils/desktop/cloud 66/projects/go_projects/src/github.com/cloud66/helloworld/helloworld  
2017/04/05 10:14:14  setting file permissions for /users/danielvangils/desktop/cloud 66/projects/go_projects/src/github.com/cloud66/helloworld/helloworld to 755  
2017/04/05 10:14:14  removing built container 3278c37f63092f70e3ef157268d3bc770f0333b550c9a10ec0527940dc677833  
2017/04/05 10:14:14  parallel build for helloworld:latest  
2017/04/05 10:14:14  building helloworld:latest  
2017/04/05 10:14:14  parsing and converting 'dockerfile.production'  
2017/04/05 10:14:14  writing the new dockerfile into dockerfile.production.generated  
2017/04/05 10:14:14  building the helloworld:latest image from dockerfile.production.generated  
step 1/4 : from scratch  
 ---> 
...
step 4/4 : cmd ./helloworld  
 ---> using cache
 ---> 31dd0a6f2cce
successfully built 31dd0a6f2cce  


$ docker images | grep helloworld

helloworld  latest  31dd0a6f2cce  24 minutes ago  3.9 mb  

now we've got the smallest possible image with only one layer, and it only contains our executable. you can even compress it more using upx , which could save up to 40% more space.

to show all the layers, run the $ docker history command.

$ docker history helloworld

image             comment                                          size  
31dd0a6f2cce      /bin/sh -c #(nop)  cmd ["./helloworld"]          0 b  
bc5aa13f774e      /bin/sh -c #(nop)  expose 8080/tcp               0 b  
33a1c4891bb1      /bin/sh -c #(nop)  copy file:bc24b3193d1b79...   3.9 mb  

summary

creating the smallest possible docker image for your golang application is easy with habitus. integrating habitus with your ci/cd pipeline gives you the control to create isolated processes with minimal attack surface.

good to know we support habitus in our buildgrid solution.

happy welding your containers.