Home

Development

Quick start

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

  • Download and install Java SDK 6, 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

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

Developer documentation

The developer documentation covers the technical architecture, the design of each module and use of the development frameworks behind DHIS 2. Feel like contributing to the documentation? Have a look at this document to get instructions on how to participate.

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.

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.
  • DHIS 2 is built with Maven. Tell Eclipse where your local Maven repository resides by navigating to Window - Preferences - Java - Build Path - Classpath Variables, then add a classpath variable by clicking New. Use M2_REPO as name and the path to your repository as path. The repository can typically be found in <user.home>/.m2/repository.
  • You can generate source code project files for Eclipse by invoking mvn eclipse:eclipse in the /dhis-2 and the /dhis-2/dhis-web directories. Import the source code projects by navigating to File - Import - General - Existing Projects into Workspace, then click Browse, locate the /dhis-2 directory and click Finish.
  • To make sure that the output folder of Eclipse does not get overwritten by Maven navigate to Window - Preferences - Java - Compiler - Building and tick Rebuild class files modified by others.
  • To improve your coding environment navigate to Window - Preferences - General - Editors - Text Editors, then tick Insert spaces for tabs, 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 -Dtest=false -DfailIfNoTests=false
  • 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.
  • To easily execute Maven goals from inside Eclipse you can set up an external launcher. This guide explains how.

Firefox tips & tricks

Firefox is the favoured browser of the DHIS 2 development team. You can get it from here.

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. 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 both JasperReports and BIRT.

  • JasperReports is included in the DHIS 2 application. To design reports you might use the iReport report designer.
  • BIRT requires the BIRT runtime webapp to be deployed in your servlet container. BIRT is based on Eclipse. To design reports you might install the BIRT plugin from the Eclipse update manager or you can download the stand-alone designer.

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

Servlet container deployment

DHIS 2 is packaged as a WAR-file and can be deployed to a Java Servlet container like Tomcat which you can download here. Deploying to Tomcat is a matter of placing the DHIS 2 WAR file inside the <installdir>/webapps directory and starting the container. The DHIS 2 portal is packaged as a WAR file by default and can found in the /dhis-2/dhis-web/dhis-portal/target directory. This guide explains how to start Tomcat, while everything else you need to know about Tomcat can be found here. Additional info on installing Tomcat on Linux can be found here.

Performance tuning

  • To allocate more memory to the Java process you can define an evironment variable JAVA_OPTS=-Xms256m -Xmx768m -XX:PermSize=256m -XX:MaxPermSize=768m. You might have to specify MAVEN_OPTS and CATALINA_OPTS in order to get Maven and Tomcat respectively to pick it up.
  • To allocate more memory to PostreSQL you can modify the <posgresql_install_dir>/<version_number>/postgres.conf configuration file and set shared_buffers=128MB In order to have this working on Linux you might have to increase the kernel shared memory by appending kernel.shmmax=268435456 to /etc/sysctl.conf