The purpose of this guide is to describe standard practices of handling Docker image build resources and Docker images to optimize collaboration and re-use.
Docker Artifact Repositories
There are three places that three different types of Docker artifacts should presently be maintained as part of the proof-of-concept effort:
- LITS Subversion: Dockerfiles, build and run scripts, and resources
- PoC Build & Package Server: package script which checks out and run Docker image builds and archives artifacts
- Emory DockerHub Registry: Docker images
When you begin creating a new image, the place to start is in LITS Subversion (emoryoit repository), specifically in <https://svn.service.emory.edu:8443/repos/emoryoit/distributions/docker/>. Here you will find example image artifacts, a project called emory-tomcat8-base-1.0. This naming convention follows our conventions for other software packaging and distribution practices. It is [organization]-[product]-[optional descriptor]-[version]. In the case of this example, it means this images is an Emory images (and not ACTSI or one of our external collaborators for which we do builds), that it is for Tomcat8, it is a base image that is intended to be used in other Docker images builds for deployment, and it is version 1.0.
To create a new image, create a new directory with a properly formed name in the distributions/docker directory in Subversion. Within your image directory you will typically have the following artifacts:
- bin directory containing scripts to build, run, push, and cleanup
- resources directory containing all software and configurations that need to be copied into your image for installations
Generally, a good way to start a new image is to just copy an existing image directory out there that seems correctly constructed and then change the artifacts within it.
Proof-of-Concept Build & Package Server
The PoC build & package server (dockerpoc1.cc.emory.edu) is just a stand-in for our real build and package server (package.cc.emory.edu). The only reason we can't use our real build & package server is that we will need to upgrade it to RHEL 7 in order to run Docker. Presumably we'll do that at some point.
To access the build & package server, request an account from the systems group that is in the group "package" and ssh to the server. To access the build & package environments, just cd to /home/package/work. Here you will find a directory for each project being packaged. To continue with the example above, you will see a directory called emory-tomcat8-base-1.0. It contains a package script and and archive directory. All of the other artifacts that appear there are ephemeral. They are created by package script as it runs.
The package script for a Docker image does six main things:
- It locks execution so the script cannot be concurrently invoked
- It creates or increments a build number
- It deletes all artifacts from previous executions of the package process
- It checks out the current Docker image artifacts from Subversion into a directory called temo-repo
- It runs the Docker buildimage.sh and pushimage.sh scripts provided in Subversion to build the image and push it to DockerHub and tags the image as latest and with the current build number
- It archives the image that was produced on the file system in the archive directory for that image product
Generally, a good way to start a new image build & package is just to copy and existing build & package environment that is properly constructed and change what is necessary for the new product name. Typically, this will just be the package name and the location in Subversion from which to check out resources.
Emory DockerHub Repository
It sounds like we may soon have our own local Docker registry at Emory, but until that time we are using a private registry in DockerHub maintained by IT Architecture. To get access to this just send Steve Wheat <firstname.lastname@example.org> you DockerHub account name and he will add you as an admin. To create a new repository, just create a new repository and flag it as private. Repositories should be named like the product you are building. For example emory-tomcat8-base-1.0 would be named emory/tomcat8-base-1.0 in DockerHub.