Development

Quick start

This section provides a quick guide to get up to speed with DHIS 2 development.

  • Download and install Java SDK 7, Bazaar and Maven.
  • If you intend to commit code to Launchpad you must register a user at Launchpad, then upload a SSH key pair and finally log in by invoking bzr lp-login <username> Also, you must be a member of a team with commit privileges to the particular branch, for trunk that is dhis2-devs-core.
  • Get a copy of the source code from Launchpad by invoking bzr branch lp:dhis2
  • To build the source code with Maven navigate to the /dhis-2 directory and invoke mvn install Then navigate to the /dhis-2/dhis-web directory and invoke mvn install again.
  • Each project in the /dhis-2/dhis-web directory is an individual web module. The dhis-web-portal project is an assembly of all the individual web modules. All of these modules can be started by invoking mvn jetty:run-war The web application can then be accessed at http://localhost:8080

Useful tools

These tools are useful for developing standard reports and working with the DHIS Web API.

Tool Description Size
Gow Over 100 extremely useful open source UNIX applications compiled as native Windows binaries 8 Mb
iReport Report development and designer tool for JasperReports and JasperReports Server 98 Mb

Knowledge base

This section contains learning resources for most development frameworks and tools used in DHIS 2. They are all open-source and pretty mainstream.

Subject Reference Slides Example code
Bazaar Reference
Maven 2 Reference Slides
Spring IOC container Reference Slides Example code
Spring AOP Reference Slides Example code
Spring Hibernate integration Reference Example code
Spring JDBC integration Reference Example code
Spring Transaction management Reference Example code
JUnit Reference Slides Example code
Hibernate Mapping Reference Slides Example code
Hibernate Queries Reference Slides Example code
Struts 2 Reference Slides Example code
Java Servlets Reference Slides

Collaboration platform

DHIS 2 uses Launchpad as its software collaboration platform. Launchpad provides bug and specification tracking, code hosting using Bazaar, mailing lists and more. To actively use Launchpad you need to register a user account by going to this page. If you have discovered a bug you can report it on the bugs page. If you want to request a feature or write a specification please do so on the blueprints page. To get an overview of the DHIS 2 source code branches please visit the source code page. The branch where the mainline development of the system takes place is called trunk. You can browse the latest checked in revisions and follow the latest registered bugs and blueprints in trunk on this page. You can browse the actual source code and its revisions in trunk on this page.

The mailing list for the DHIS 2 developer team is attached to the general developer team in Launchpad. This team is called dhis2-devs and is an open team, which means that everyone with a Launchpad account can be a member. First visit the team home page and sign up for the team. Then sign up for the mailing list by clicking the subscribe button under the mailing list heading. The address to post to is dhis2-devs at lists.launchpad.net.

Collaboration conventions

  • If you want to contribute to the development of DHIS 2 by implementing a piece of functionality you should create a separate source code branch. This branch will be used as basis for discussions of the solution and code peer review. When the functionality is implemented please send an email to the DHIS 2 developer list describing what you have done and request feedback.

    You could either create one branch for each piece of functionality or, if you are on a slow internet connection and only work on one piece of functionality at the time, create a generic branch and reuse it. To create and maintain a branch do the following:

    • Use a local unmodified trunk and branch locally with bzr branch <path-to-trunk> branch-name (you have to come up with the branch-name yourself, should be descriptive).
    • Navigate to branch directory and push to Launchpad with bzr push lp:~dhis2-devs-core/dhis2/branch-name This tells Launchpad that dhis2-devs-core is the owner, dhis2 is the project, and [branch-name] is the name of your branch. The branch will appear the branches page.
    • Set the commit destination for your branch with bzr bind lp:~dhis2-devs-core/dhis2/branch-name
    • Merge regularly with trunk in order to make it easier to integrate the solution in the end by doing bzr merge lp:dhis2

    A few rules apply when working with the source code branches:

    • Never use bzr push! Pushing will replace the content in trunk which means that the revision history will be lost. It is also prone to merging mistakes like overwriting other work in trunk.
    • Never use bzr uncommit! If you have made a mistake and want to fix it, then do bzr merge -r 100..90 (replace 100 and 90 with the revisions you want to remove) and commit as usual. Un-comitting will lead to problems as the lastest changes will be appear as diff in all existing working copies when they are updated.

    When its time to merge your branch with trunk, given that you have the required authority, please follow these steps:

    • Merge your branch with trunk with bzr merge lp:dhis2 and the commit as usual to your branch.
    • Navigate to a checkout of trunk and update it with bzr update.
    • Merge with bzr merge lp:~dhis2-devs-core/dhis2/branch-name (replace branch-name with the name of your branch).
    • Go through the changes with bzr status and bzr diff.
    • Commit your changes.
  • Before merging with trunk it's required to run all unit tests in the system. Be aware that you are working on a large system and that changes you do might conflict with other modules.
  • When committing code in response to a blueprint or bug, indicate that in your commit message by referring to title or number. Similarly, when marking a blueprint or bug as complete, indicate the revision number in a comment.
  • Follow the DHIS 2 code style and make sure your code looks like the rest (whether you like it or not).

Eclipse tips & tricks

Eclipse is the favoured IDE of the DHIS 2 development team. You can get it from here.

  • Import the DHIS 2 code style by downloading the profile from here. In Eclipse navigate to Window - Preferences - Java - Code Style - Formatter, then import the profile by clicking Import, locate your downloaded file and click Open. Then in Eclipse you can format your Java code with Shift-Ctrl-F.
  • DHIS 2 is built with Maven so installing the m2eclipse plugin is strongly recommended as it makes building and importing dependency libraries much simpler. Install from within Eclipse from Help -> Install New Software and use http://download.eclipse.org/technology/m2e/releases as update site.
  • To improve your coding environment navigate to Window - Preferences - General - Editors - Text Editors, then tick Show print margin and Show line numbers.
  • To change the text font navigate to Window - Preferences - General - Appearance - Colors and Fonts - Basic - Text Font - Edit.
  • To speed up building the source code by omitting the test phase invoke mvn clean install -DskipTests=true
  • A useful Eclipse plugin for Velocuty templates is Velocity Web Edit which can be downloaded here. A good plugin for XML files is XmlBuddy which can be downloaded here. Installation instructions for a useful plugin for Javascript files called JSEclipse can be found here. A good plugin for CSS files is CSS Editor which can be found here.

Netbeans tips & tricks

Netbeans is the favored IDE of some of the DHIS 2 development team. You can get it from here. One tricky aspect of using netbeans on dhis is to configure netbeans to deliver (approximately) the same code style as our eclipse comrades.

You can download a reasonably complete approximation of the DHIS style for netbeans from the link provided. Import it into netbeans using Tools->Options then look for the "Import" button at the bottom of the dialog. Just to be safe, you might want to export your current settings first, using the "Export" button in the same dialog. Please consider contributing any improvements to this set of style settings.

Intellij IDEA tips & tricks

Intellij IDEA is a nice IDE for Java development. You can get an approximate dhis code style from this link.

I18n

The DHIS 2 user interface is fully internationalized and comes with a whole range of languages. If you are setting up DHIS 2 you might want to provide translations for the language of your country or improve the existing translations. To facilitate this process you might download and use the i18n resource editor from the downloads page. To start it simply unpack the archive and on Windows click the executable file, or on Linux invoke the startup script. Then browse to the root of the source code tree (dhis2/dhis-2), click OK and you are good to go.

Report design

DHIS 2 integrates with JasperReports, which is included in the DHIS 2 application. To design reports you might use the iReport report designer.

Web browsers

DHIS 2 can be used with all major browsers. For Internet Explorer version 8 or higher is recommended. For development purposes, Chrome is recommended due to its high performance and create developer console - click F12 to open it and use the Elements, Network and Console actively.

Database setup

DHIS 2 contains an embedded H2 database which will be used in-memory if no configuration is found. If you prefer to develop against a standard database we recommend that you use PostgreSQL which you can download here. Installation is pretty straight-forward, if you need guidance you can have a look at the excellent official tutorial. If you want to learn more you can consult the official documentation. Remember to let the user you want to connect with be the owner of the database. If you have problems connecting to the database on Linux you can consult this guide.

To configure the database connection you will need to create a configuration file called hibernate.properties. To tell DHIS 2 where to look for that file you will have to define an environment variable with the name DHIS2_HOME, pointing to the directory where you put the configuration file.

The contents of the hibernate.properties file would be something like this, where the database name is dhis2 and the user name and password are dhis.

hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect
hibernate.connection.driver_class = org.postgresql.Driver
hibernate.connection.url = jdbc:postgresql:dhis2
hibernate.connection.username = dhis
hibernate.connection.password = dhis
hibernate.hbm2ddl.auto = update

If you are already committed to using MySQL you can download the latest version here. Documentation can be found here. The corresponding hibernate.properties looks like this.

hibernate.dialect = org.hibernate.dialect.MySQLDialect
hibernate.connection.driver_class = com.mysql.jdbc.Driver
hibernate.connection.url = jdbc:mysql://localhost/dhis2
hibernate.connection.username = dhis
hibernate.connection.password = dhis
hibernate.hbm2ddl.auto = update

H2 is a handy database that can be used embedded and in-memory as well as external and and persisted to a file. Note that the database files needs write privileges. The corresponding hibernate.properties looks like this:

hibernate.dialect = org.hibernate.dialect.H2Dialect
hibernate.connection.driver_class = org.h2.Driver
hibernate.connection.url = jdbc:h2:/abs-file-path-without-extension;AUTO_SERVER=TRUE;DB_CLOSE_ON_EXIT=FALSE
hibernate.connection.username = sa
hibernate.connection.password =
hibernate.hbm2ddl.auto = update

Installation

DHIS 2 runs on any operating system where a JVM is available. On Windows you can use the DHIS 2 Live package which contains an embedded Jetty web server and an embedded H2 database. On Linux you can follow the installation guide which you will find in the implementation guide on the documentation page.