GitHub   @OpenKivaKit Twitter Zulip Chat RSS Feed Java Code Geeks Mailing List


Jonathan's thoughts on the state of the art in software design.


KivaKit - Docker Build Environment   

KivaKit 1.2.3 provides a Docker build environment that makes it easy to build KivaKit without installing software or configuring the build environment.

Launching the Build Environment   

Once Docker has been installed, the KivaKit Docker build environment can be launched with a few simple commands:

export KIVAKIT_WORKSPACE=~/workspaces/kivakit

git clone --branch develop
bash $KIVAKIT_WORKSPACE/kivakit/setup/

export KIVAKIT_BUILD_IMAGE=1.2.3-snapshot

docker run \
    --volume "$KIVAKIT_WORKSPACE:/host/workspace" \
    --volume "$HOME/.m2:/host/.m2" \
    --volume "$HOME/.kivakit:/host/.kivakit" \
    --interactive --tty "jonathanlocke/kivakit:$KIVAKIT_BUILD_IMAGE" \

The build environment can build source code in a workspace on the host as well as inside Docker, so the first line above specifies the host workspace. The next four lines clone all the required repositories into that workspace. The second export line then specifies the KivaKit Docker tag to launch. Finally, the docker run command launches the build environment.

Build Scripts   

Several build scripts are available in the Docker build environment, and they are all made available on our shell’s PATH. To build KivaKit, we would use Since this script is on our PATH, we can build KivaKit without changing our current working directory with cd:

We can see all available KivaKit scripts by typing kivakit- followed by TAB. Here are some of the more important scripts:

KivaKit Script Purpose Show KivaKit version Build KivaKit Build KivaKit documentation Pull changes from GitHub ** [branch] Check out the given branch ** Switch between host and Docker workspaces [branch] Start a git flow feature branch ** [branch] Finish a git flow feature branch **

** executes the command in each kivakit repository

Build Workspaces   

When the Docker build environment starts up, it is set up to build a workspace provided inside the container. This baseline build should work nearly all of the time, because the build environment is standardized, and the build should have worked at the time the Docker image was created. Having a common, standardized build environment provides us with an easy way to determine if there’s a problem in the source code versus a build environment problem. If the Docker workspace builds successfully, we can be fairly sure that there is nothing wrong with code, even if the host workspace build fails.

The script allows us to switch between the Docker and host workspaces. Initially, the workspace inside the Docker container is set up to build. If we want to switch to the host workspace, we can issue this command (use TAB to complete the long script name): host

Switching to the host workspace will allow us to do an initial build of the code we cloned into that workspace above. Once the host workspace has been built, KivaKit projects can be imported into an IDE like IntelliJ.

But how does workspace switching work?

Notice that the docker run command has three Docker –volume mounts. The –volume switch makes a host folder visible inside a Docker container:

--volume [host-folder]:[docker-folder]

So, the docker run command we issued above makes these three host folders available under the /host folder inside Docker:

Docker Mount Folder Host Folder
/host/workspace $KIVAKIT_WORKSPACE
/host/.m2 $HOME/.m2
/host/.kivakit $HOME/.kivakit

When we start up the Docker build environment, the KIVAKIT_WORKSPACE environment variable points to a workspace in the /root folder inside our container, and the symbolic links /root/.m2 and /root/.kivakit point to folders under /root/developer, also inside our container:

Docker Reference Target Folder
KIVAKIT_WORKSPACE /root/workspace
/root/.m2 /root/developer/.m2
/root/.kivakit /root/developer/.kivakit

When we switch to the host workspace, the KIVAKIT_WORKSPACE environment variable and the symbolic links are switched to point to folders that have been mapped into the Docker container from the host (using the –volume mount switches, as described above). Now our environment looks like this:

Docker Reference Target Folder
KIVAKIT_WORKSPACE /host/workspace
/root/.m2 /host/.m2
/root/.kivakit /host/.kivakit

and, when we execute in Docker, the host’s workspace will be built, using our standardized Docker build environment.


The scripts for the KivaKit Docker build environment are here:

Questions? Comments? Tweet yours to @OpenKivaKit or post here:

Copyright © 2021 Jonathan Locke