Build your own Jenkins! Introducing Custom WAR/Docker Packager

As with Jenkins itself, Custom WAR Packager started as a small development tool. For a long time it was a problem to run integration testing in Jenkins. We have 3 main frameworks for it: Jenkins Test Harness, Acceptance Test Harness, and Plugin Compatibility Tester. All these frameworks require a Jenkins WAR file to be passed to them to run tests. What if you want to run Jenkins tests in a custom environment like AWS? Or what if you want to reuse existing Jenkins Pipeline tests and to run them against Pluggable Storage to ensure there are no regressions?

And it was not just an idle question. There were major activities happening in the Jenkins project: Cloud-Native Jenkins, Jenkins Evergreen, and Jenkins X. All these activities required a lot of integration testing to enable Continuous Delivery flows. In order to do this in existing test frameworks, we needed to package a self-configuring WAR file so that it would be possible to run integration tests in existing frameworks. That is why Custom WAR Packager was created in April 2018. Later it got support for packaging Docker images, and in September 2018 it also got support for Jenkinsfile Runner which was created by Kohsuke Kawaguchi and then improved by Nicolas de Loof.

Custom WAR packager is a tool which is available as CLI Executable, Maven Plugin, or Docker package. This tool takes input definitions and packages them as requested by the user. Everything is managed by a YAML configuration file:

The tool supports various types of inputs. The list of plugins can be passed via YAML itself, pom.xml, or a BOM file from JEP-309. Custom WAR Packager supports not only released versions, but also builds deployed to the Incremental repository (CD flow for Jenkins core and plugins - JEP-305) and even direct builds by Git or directory path specifications. It allows building packages from any source, without waiting for official releases. The builds are also pretty fast, because the plugin does caching in the local Maven repository by using commit IDs.

Custom WAR packager also supports the following self-configuration options:

WAR packaging happens by default every time the repo is built. Generally Custom WAR Packager repackages all inputs into a single WAR file by following conventions defined in the Jenkins core and the JCasC plugin.

Sample configuration:

In order to do the Docker packaging, Custom WAR Packager uses the official jenkins/jenkins Docker images or other images using the same format. During the build the WAR file just gets replaced by the one built by the tool. It means that ALL image features are available for such custom builds: plugins.txt, Java options, Groovy hooks, etc., etc.

For example, this demo shows packaging of a Docker image with External Build Logging to Elasticsearch. Although the implementations have been improved as a part of JEP-207 and JEP-210, you can check out this demo to see how the Docker image does self-configuration, connects to a Elasicsearch, and then starts externally storing logs without changes in build log UIs. A Docker Compose file for running the entire cluster is included.

This is probably the most tricky mode of Jenkinsfile Runner. In March a new Jenkinsfile Runner project was announced in the developer mailing list. The main idea is to support running Jenkins Pipeline in a single-shot controller mode when the instance just executes a single run and prints outputs to the console. Jenkinsfile Runner runs as CLI or as a Docker image. Custom WAR Packager is able to produce both, though only Docker run mode is recommended. With Jenkinsfile Runner you can run Pipelines simply as…​

When we started working on Ephemeral (aka "single-shot") controllers in the Cloud Native SIG, there was an idea to use Custom WAR Packager and other existing tools (Jenkinsfile Runner, Jenkins Configuration as Code, etc.) to implement it. It would be possible to just replace Jenkins core JAR and add plugins to Jenkinsfile Runner, but it is not enough. To be efficient, Jenkinsfile Runner images should start up FAST, really fast. In the build flow implementation we used some experimental options available in Jenkins and Jenkinsfile Runner, including classloader precaching, plugin unarchiving, etc, etc. With such patches Jenkins starts up in few seconds with configuration-as-code and dozens of bundled plugins.

So, how to build custom Jenkinsfile Runner images? Although there is no release so far, it is not something which can stop us as you see above.

You can find a Demo of Jenkinsfile Runner packaging with Custom WAR Packager here.

There are many other features which are not described in this blogpost. For example, it is possible to alter Maven build settings or to add/replace libraries within the Jenkins core (e.g. Remoting). Please see the Custom WAR Packager documentation for more information. There are a number of demos available in the repository.

If you are interested to contribute to the repository, please create pull requests and CC @oleg-nenashev and Raul Arabaolaza who is the second maintainer now working on Jenkins test automation flows.

There are still many improvements that could be made to the tool to make it more efficient:

Many other tasks could be implemented in Custom WAR Packager, but even now it is available to all Jenkins users so that they can build their own Jenkins bundles with it.

If you are going to DevOps World - Jenkins World in Nice on Oct 22-25, I will be presenting Custom WAR Packager at the Community Booth during the lunch demo sessions. We will be also repeating our A Cloud Native Jenkins talk together with Carlos Sanchez where we will show how Ephemeral Jenkins works with Pluggable Storage. Jenkins X team is also going to present their project using Custom WAR Packager.