Skip to content

Running DHIS 2 with JRebel

Jump to bottom
Halvdan Hoem Grelland edited this page Nov 17, 2016 · 13 revisions

JRebel allows instant code re-deploy for running Java apps. As DHIS 2 has a substantial compile-and-startup time, this is obviously useful for backend (Java) development.

Due to the nested multi-module structure of the application, however, JRebel is not straightforward to set up with DHIS 2. This is a small tutorial which aims to give an idea of how to set up a basic development environment for DHIS 2 using JRebel, Maven and embedded Jetty, running from the command line.

That is, this can surely be done for other servlet containers (e.g. Tomcat) too, but we focus on mvn jetty:run for simplicity.

Also note that this tutorial uses JRebel as a stand-alone, binding directly to the lib and jar. Most methods rely on IDE plugins to do the hard configuration work, but this turned out to not work well for DHIS 2 (at least for the author of this guide).

What you need

  • The dhis2-core source code
  • A Linux/Unix/macOS environment
  • A JRebel license (for evaluation get a trial or use myJrebel (only personal use!)
  • An intallation of JRebel. Could be stand-alone or could be through an IDE (e.g. IntelliJ JRebel plugin), doesn't matter.

Steps

Generate rebel.xml files

In order for JRebel to interoperate with a maven module a rebel.xml file is needed. Creating these manually is tedious, so we generate them.

DHIS 2 is set up with the rebel-maven-plugin which takes care of this for us. You can run it manually on a module in DHIS 2 like so:

mvn rebel:generate

This quickly gets tedious to do for each module, though. Running the build with the -Pdev flag takes care of running the rebel plugin for you:

mvn install -Pdev

Make sure you do this for the web modules too, so starting from the dhis-2 directory:

mvn intstall -Pdev && cd dhis-web && mvn install -Pdev

You can validate that file exists by looking for /target/classes/rebel.xml in any of the modules.

Configure enviroment

In order to run mvn jetty with JRebel we need maven itself to run with the JRebel javaagent. There are many ways to go about doing so, and it's probably painless in certain (Linux?) environments (or when running through Eclipse/IntelliJ). In the case of the author, however, it wasn't trivial to figure out (Mac OS X).

The basic requirements are:

  • Setting up the REBEL_BASE, JREBEL_AGENT and JREBEL_LIB environment variables.
  • Ensuring the JRebel javaagent is bootstrapped with Maven when needed (when we want it to)

For the first point the configuration looks like this (modification required for your setup):

JREBEL_AGENT=/path/to/jrebel6/jrebel.jar
JREBEL_LIB=/path/to/jrebel6/lib/libjrebel64.{dylib|so|dll}
REBEL_BASE=/path/to/some/writable/folder # I use ~/.jrebel

The jrebel6 artifacts referenced will be found in your JRebel installation. If you installed using a plugin it will, for example, reside within the plugin installation directory.

Note also that for IntelliJ + Mac the path will contain spaces (because of the pesky Application Support folder). Such paths are not welcome in MAVEN_OPTS, and should be avoided. The author solved this issue by directing through symlinks in /usr/local/bin/xxx.{jar|dylib}.

Clone this wiki locally