wharfie

Wharfie is a tool for building reproducable Docker images. Wharfie produces ready-to-run images by injecting a user source into a docker image and /preparing/ a new Docker image which incorporates the base image and built source, and is ready to use with docker run. Wharfie supports incremental builds which re-use previously downloaded dependencies, previously built artifacts, etc. Interested in learning more? Read on!

Basic wharfie builds

Wharfie accepts the following inputs to do a build:

1. Application source: this can be source code, zipped source, a binary, etc.
2. Wharfie source image: the basis for the new image to build
3. Prior build image: optional, a previously built wharfie output image to pull build artifacts from

The build process is as follows:

1. Wharfie pulls the source image if it is not already present on the system
2. Wharfie generates a Dockerfile to describe the output image:
   1. Based on the wharfie source image
   2. Adds the application source at /usr/source in the container
   3. Calls /usr/bin/prepare in the container
   4. Sets the image's default command to /usr/bin/run
3. Wharfie builds the new image from the Dockerfile using docker build

Anatomy of a wharfie source image

Building wharfie source images is as easy as implementing two scripts. Wharfie expects the following scripts in /usr/bin:

1. prepare : This script is responsible for building and/or deploying the source
2. run: This script is responsible for running the deployed source

Incremental wharfie builds

When you call wharfie build with the --incremental flag, the build process is as follows:

1. Wharfie pulls the source image if it is not already present on the system
2. Wharfie pulls the incremental build image if it is not already present on the system
3. Wharfie creates a new docker container from the prior image, with a volume in /usr/artifacts
4. Wharfie runs /usr/bin/save-artifact in this container
5. Wharfie creates a new docker container from the source image, mounting the volumes from the incremental build container
6. Wharfie bind-mounts the application source into /usr/source in the container
7. Wharfie runs /usr/bin/restore-artifact to restore the build context from the prior image
8. Wharfie calls /usr/bin/prepare in the container
9. Wharfie commits the container as a new image, setting the new image's command to /usr/bin/run

There are two more scripts to implement to support incremental builds:

1. save-artifact: This script is responsible for moving build dependencies to /usr/artifacts
2. restore-artifact: This script is responsible for restoring a build environment from /usr/artifacts

Getting started