Publishing Docker Images with Automated Builds

photo credit: Tesla Robot Dance via photopin (license)

I’ve been cranking away at Docker in Action and am excited to announce the availability of Chapter 9 (Public and Private Software Distribution) to MEAP readers. There are a few rough spots and it should be updated again in the next few weeks, but I wanted to get the content out as early as possible. You can get access to the MEAP or buy the book at http://www.manning.com/nickoloff. What follows is an excerpt from that chapter.

A few different hosted registries offer automated builds. Automated builds are images that are built by the registry provider using image sources that you’ve made available. Image consumers have a higher degree of trust for these builds because the registry owner is building the images from source that can be reviewed.

Distributing your work with automated builds requires two components: a hosted image repository, and a hosted Git repository where your image sources are published. Git is a popular distributed version control system. A Git repository stores the change history for your project. While distributed version control systems like Git do not have architectural centralization, there are a few popular companies that provide Git repository hosting. Docker Hub integrates with both Github.com and Bitbucket.org for automated builds.

Both of these hosted Git repository tools provide something called, “webhooks.” In this context, a webhook is a way for your Git repository to notify your image repository that a change has been made to the source. When Docker Hub receives a webhook for your Git repository it will start an automated build for your Docker Hub repository.

The automated build process pulls the source for your project including a Dockerfile from your registered Git repository. The Docker Hub build fleet will use a docker build command to build a new image from those sources, tag it in accordance with the repository configuration, and then push it into your Docker Hub repository.

Creating a Docker Hub Automated Build

The following example will walk you through the steps required to setup your own Docker Hub repository as an automated build. This example uses Git. Whole books have been written about Git and so it cannot be covered in detail here. Git ships with several operating systems today, but if it is not installed on your computer or you need general help check their website at https://git-scm.com/. For the purposes of this example you need accounts on both Docker Hub and Github.com.

Login to your Github.com account and create a new repository. Name it, “hello-docker” and make sure that the repository is public. Do not initialize the repository with a license or a .gitignore file. Once the repository has been created on Github, go back to your terminal and create a new working directory named, “hello-docker.”

Create a new file named Dockerfile and include the following lines:

FROM busybox:latest
CMD echo Hello World

This Dockerfile will produce a simple “hello world” image. The first thing you need to do to get this built into a new repository at Docker Hub is add it to your Git repository. The following Git commands will create a local repository, add the Dockerfile to the repository, commit the change, and push your changes to your repository on Github. Be sure to replace <your username> with your Github username.

git init
git config — global user.email “you@example.com”
git config — global user.name “Your Name”
git add Dockerfile
git commit -m “first commit”
git remote add origin https://github.com/<your username>/hello-docker.git
git push -u origin master

When you execute the last command, you may be prompted for your Github.com login credentials. After you do, your work will be uploaded to Github and you can view your Dockerfile online.

Now that your image source is available online at Github, you are ready to create a new automated build at Docker Hub. This step must be done through their website at https://hub.docker.com/. Once you login, click the “Add Repository” button, and select “Automated Build” from the dropdown menu. The website will walk you through setting up the automated build.

The steps include authenticating with Github and granting Docker Hub limited access to your account. That access is requires so that Docker Hub can find your repositories and register appropriate webhooks for you. The setup process will prompt you for the Github repository that you would like to use for the automated build. Select the “hello-docker” repository that you just created. Once you finish the rest of the creation wizard, you should be presented with a link to a build details page. Follow that link, and once the pages indicates that the build has been completed you should be able to search for your new repository from the Docker command line.

docker search <your username>/hello-docker
# Outputs:
# NAME DESCRIPTION STARS OFFICIAL AUTOMATED
# <your username>/hello-dockerfile 0 [OK]

Automated builds are preferred by image consumers, and simplify image maintenance for most cases.