Ready for some practical tricks on how to use the build system? Create custom builds, deterministic builds, reproduce specific builds, and more!
This is a follow-up to the build system overview, if you haven't, read that first!
Below are some examples of use cases, and if you want to cross-reference the build system diagrams, the services interacting from this point are:
- GitHub (d2-ci)
- GitHub (dhis2)
What can we do with it?
The primary use cases which are useful to be aware of are:
- Answer questions about a build
- Create custom builds
- Control when to fetch new apps
Answer questions about a build
What are the bundled applications in a build?
dhis-web-apps module serves all the apps which were bundled into the
WAR at build time and includes the time the WAR-file was assembled and from
which commit it was created from.
Example build information
Mon Mar 25 2019 15:37:12 GMT+0000 (UTC)
Exactly what versions of the apps does a build contain?
To get a list of applications along with a reference to the exact build of the
application you can query the
dhis-web-apps module for the
Each of the
refspec points to the d2-ci repo of the
application which stores all the
build artifacts for apps:
E.g. for the Data Quality App the build included is: https://github.com/d2-ci/data-quality-app/commits/3166be606054bb7f5a979c041048450d97e1e6fe
What is the source commit for a given application build?
apps-bundle.json file references the commit of the build artifact. This
is useful for referencing specific builds, but as a developer you might be more
interested in the source code commit from which the build was created.
Each application exposes a
BUILD_INFO file which is available through the
The commit hash in
BUILD_INFO points to the source repo in the DHIS2 organisation:
Fri Nov 9 23:19:00 UTC 2018
Create custom builds
To change which apps and respective versions of the apps are bundled, a single file needs to be modified in dhis2-core:
This is a JSON file which contains an array with Git repositories. The
build scripts for
dhis-web-apps then use Git to clone the respective
element in the list.
The Git repos we use to bundle applications is a build artifact repository. For every app repo on the github.com/dhis2 org, we have a build repo on github.com/d2-ci to store the build artifacts for each build (one per commit).
https://is used for the apps to avoid the build environment having a git+ssh set up. If you know that you can clone from a
git://URL then that is fine to use as well.
For each of the referenced Git URLs it is possible to specify what tree-ish should be used for the build. The syntax for that is:
- Can be a commit:
- Or a branch:
- Or a tag:
Some example use cases below:
Replicate a specific build
Say that you are running 2.31.0 in production today, and you know that the applications in that version are good. Then version 2.31.1 is released and the pre-built WAR-file comes with application updates which you do not want. This might be due to your test procedures of having to do a full regression test on all updated applications.
So you decide that you want to keep the applications versions in their known good state and see if you can update only the core from 2.31.0 to 2.31.1.
First you download the https://play.dhis2.org/2.31.0/dhis-web-apps/apps-bundle.json file, which includes the exact build artifact refspecs for the applications which were bundled with the WAR-file when it was originally built.
Then checkout the branch for 2.31.1 in the
dhis2-core repository and put
the contents of
dhis2-core/dhis-2/dhis-web/dhis-web-apps to bundle the specified application
Execute the build and you will get a 2.31.1 build with the applications you had in your 2.31.0 instance.
Customize your build
Remember the syntax outlined above:
Here is a deeper dive into how to use the part following the hash (
Default: use master branch
#<treeish> is left out, then the default behaviour is to fetch the
latest build from the
#master to the app URL to do so explicitly.
Use arbitrary branches
To test the latest build from a branch append it to the URL after the hash
This allows your build to track the latest build from a specific branch, and is what we do for our development environments, for example. It is also handy when you are working on a feature branch and want to be able to deploy it for testing/verification/sharing, etc.
Lock to a specific commit
Sometimes there is a need to lock the core to track a specific commit, either to reproduce a build or to lock the build to a known good commit while a broken application is being fixed to stop the broken build from being put into a production build.
Any tree-ish will do after the hash (
#), so a commit SHA is also fine:
Lock to a tag
A tag also works as a tree-ish, so the formal DHIS2 releases track an application tag, so the 2.31.0 version would track the 2.31.1 tags of the applications.
Control when to fetch new apps
It is important to note that we try to align as close as possible with
how Maven works. When the
dhis-web-apps module is built it pulls in
all the web applications defined in
apps-to-bundle.json into the
dhis-web-apps/target directory. This is the default behavior to ensure
that the build system is built using the correct artifacts.
This allows Maven to have control over when the directory is due for a clean up.
This also means that if you use
mvn clean install, the
dhis-web-apps/target directory is going to be removed and all apps
are refreshed from d2-ci!
It is optimized to perform as shallow a clone as is possible, but in some cases, it needs to fetch additional commits to find a specific one.
In general, using a branch or tag is fast, using a specific commit is slow.
In offline scenarios, there are two strategies to avoid downloading apps, depending on your needs.
Strategy One: Use
mvn install if possible
If it is possible to do an incremental build, the scripts in
dhis-web-apps will first check if the apps that are necessary are in
dhis-web-apps/target, and if they are, will use those for your bundle.
It is the
clean that causes the
target directory to be wiped, so if
you avoid that, you will reuse the cached apps.
Strategy Two: Use the ignore module flag:
Sometimes it is unavoidable that you must use
mvn clean install, and
if you still do not want to refresh the apps there is an alternative.
For example to do a
clean install in
dhis-web, except for
mvn clean install -Pdev -f dhis-web/pom.xml -pl !dhis-web-apps
By now you should have an idea of how the build system operates and some tricks you can pull off with it.
Want a minimal
dhis2-core build? Remove all the apps from the
Want to share a single app with a feature branch? Create a build with a single app referencing that feature branch!
And so on.
As a final note, this build system is available for DHIS2 from 2.29 going forward.
Hope this was helpful to read and reach out if you have any questions about it.