In my previous post I described how I created a stack definition including my Node.js web application and a MongoDB service using docker-compose. In this article I will describe the steps I took to link my GitHub and Docker Hub accounts in order to automatically build a docker image triggered by a git push command.
Trigger a Build of the MedRec API Docker Image on Docker Hub
Combining internet / cloud based services such as GitHub and Docker Hub allows developers to experience productivity gains without having to fund a local server to provide this capability. I wanted to explore and experience this for myself.
Link Docker Hub and Git Hub accounts
As I didn’t have a docker account for my user I pointed my browser to docker hub … https://hub.docker.com/ and clicked the SignUp option.
I am prompted for dockerID, email address and a password. Once I got through the registration process and verified my email address, then, I was ready to get started.
I simply use the Sign-in option on the Docker hub site.
I entered my username ( barackd222 ) and password.
I clicked on the down arrow next to my username to reveal a sub menu. I chose Settings.
I chose the option on the third tab – Linked Accounts and Services
I clicked the Link GitHub icon.
I selected Public and Private (Recommended) option and then signed into GitHub.
Having authenticated to GitHub I now Authorise Docker Hub to be part of the OAuth trust.
You can see from the image below that my Docker Hub is now linked to my GitHub account.
From the Docker official documentation ; You can build your images automatically from a build context stored in a repository.
A build context is a Dockerfile and any files at a specific location.
For an automated build, the build context is a repository containing a Dockerfile.
Automated Builds have several advantages:
- Images built in this way are built exactly as specified.
- The Dockerfile is available to anyone with access to your Docker Hub repository.
- Your repository is kept up-to-date with code changes automatically.
As I want an automatic build of my docker image triggered by GitHub events I need to define my Automated Build.
I already have a Dockerfile in my ankimedrec-apis, so once I configure the automated build I should be good to go.
Under the Create sub menu I chose Create Automated Build. This is where I specify the project git repository that I want Docker Hub to subsribe to for events.
I clicked the Create Auto-build GitHub icon.
From the list of repositories associated with my git hub account I chose my git project – ankimedrec-apis.
In the Create Automated Build page I specified a repository name for my docker repository and a description, then pressed the Create button.
Set up Docker Hub to do an automated build based on changes to the Master Branch of the git repository
The steps required are very well documented but I have recorded them here so that my blog post is pretty much self-contained. The first time you create a new automated build, Docker Hub builds your image. Within a few minutes, you should see a newly built image appear on the Docker Hub image Dashboard.
The Build Details page shows a log of your build requests
A few bullet points gleaned from the official documentation.
- During the build process, Docker copies the contents of your Dockerfile to Docker Hub. The Docker community (for public repositories) or approved team members/orgs (for private repositories) can then view the Dockerfile on your repository page.
- The build process looks for a README.md in the same directory as your Dockerfile. If you have a README.md file in your repository, it is used in the repository as the full description. If you change the full description after a build, it’s overwritten the next time the Automated Build runs. To make changes, modify the README.md in your Git repository.
- You can only trigger one build at a time and no more than one every five minutes. If you already have a build pending, or if you recently submitted a build request, Docker ignores new requests.
- The Build Settings page allows you to manage your existing automated build configurations and add new ones. By default, when new code is merged into your source repository, it triggers a build of your DockerHub image.
Docker builds everything listed whenever a push is made to the code repository. If you specify a branch or tag, you can manually build that image by pressing the Trigger.
If you use a regular expression syntax (regex) to define your build branch or tag, Docker does not give you the option to manually build.
To add a new build:
Press the + (plus sign).
Choose the Type.
You can build by a code branch or by an image tag.
Enter the Name of the branch or tag.
You can enter a specific value or use a regex to select multiple values.
Enter a Dockerfile location.
Specify a Tag Name.
Press Save Changes.
If you make a mistake or want to delete a build, simply press the minus sign and then Save Changes.
Repository links let you link one Automated Build with another. If one Automated Build gets updated, Docker triggers a build of the other. This makes it easy to ensure that related images are kept in sync.
You can link more than one image repository. You only need to link one side of two related builds. Linking both sides causes an endless build loop.
Remote Build triggers : To trigger Automated Builds programmatically, you can set up a remote build trigger in another application such as GitHub or Bitbucket.
When you Activate the build trigger for an Automated Build, it supplies you with a Token and a URL.
Using Git, add new/updated files (eg Dockerfile), commit, and push the project to public Git Hub
OK, now I am ready to try this out in terms of an end to end test. I have done the necessary linking and configuration for a docker image to be created based on a git push from my local development environment to GitHub. As I cloned down from GitHub, my origin is set to the remote repository.
First I need to add my newly created (or any updated) files to my local git repository;
git add Dockerfile docker-compose.yml occs-stack.yml
Next I have to git commit the new / changed files
git commit -m “New files added to support Dockerisation of my Node / MongoDB app”
And finally I need to push my changes to update my remote branch. I used the master branch but typically you may be working on a development or feature branch.
git commit origin master
Confirm that the docker image was built by viewing Docker Hub
In docker hub navigate to the Build Details tab. You will see when the docker image is being built something like the following screenshot;
This means that the docker image for my SwaggerUI / APIs (web tier) has been built based on a code change (new file) that was pushed from my local Dev environment back to GitHub. The Docker image for my web app can now be referenced using the Docker Hub registry. I am now ready to see if I can pull this image and the pre-built MongoDB image from Docker Hub into OCCS. Read about it in the final episode in this series.