KivaKit – Docker Build Environment

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 ScriptPurpose
kivakit-version.shShow KivaKit version
kivakit-build.shBuild KivaKit
kivakit-build-documentation.shBuild KivaKit documentation
kivakit-git-pull.shPull changes from GitHub ** [branch]Check out the given branch **
kivakit-docker-build-workspace.shSwitch 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 FolderHost Folder

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 ReferenceTarget Folder

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 ReferenceTarget Folder

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:

Published on Java Code Geeks with permission by Jonathan Locke, partner at our JCG program. See the original article here: KivaKit – Docker Build Environment

Opinions expressed by Java Code Geeks contributors are their own.

Jonathan Locke

Jonathan has been working with Java since 1996, and he was a member of the Sun Microsystems Java Team. As an open source author, he is originator of the Apache Wicket web framework (, as well as KivaKit (, @OpenKivaKit) and Lexakai (a tool for producing UML diagrams and Markdown indexes from Java source code, available at, @OpenLexakai). Jonathan works as a Principal Software Architect at Telenav (, and in the future, Telenav will release further toolkit designed and led by Jonathan called MesaKit, focused on map analysis and navigation.
Notify of

This site uses Akismet to reduce spam. Learn how your comment data is processed.

Inline Feedbacks
View all comments
Back to top button