Building the source code

This page explain how to build the source code and run the application. You can run the application with or without a database.
Before you can build and run the application you have to set up your system according to Development environment and tools.

Build the code:

Step 1 - Build the source code

First, create an environment variable called JAVA_OPTS, and set its value to: -Xms128m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=512m

Windows batch script

set start_time=%time%
echo Building DHIS 2 Core
cd trunk\dhis-2\
call mvn clean install -Dtest=skip -DfailIfNoTests=false
echo Building DHIS 2 Web
cd dhis-web
call mvn clean install -Dtest=skip -DfailIfNoTests=false
echo Packing DHIS 2 Web Portal
cd dhis-web-portal
call mvn clean package -Dtest=skip -DfailIfNoTests=false
cd ..\..\..\..
echo start %start_time%
echo finish %time%

Linux shell script

#!/bin/sh
echo "Building DHIS 2 Core..."
cd dhis/trunk/dhis-2
mvn clean install -Dtest=skip -DfailIfNoTests=false
echo "Building DHIS 2 Web..."
cd dhis-web
mvn clean install -Dtest=skip -DfailIfNoTests=false
echo "Packing DHIS 2 Web Portal..."
cd dhis-web-portal
mvn clean package -Dtest=skip -DfailIfNoTests=false
cd

The resulting war is located in trunk/dhis-2/dhis-web/dhis-web-portal/target.

Possible custom configurations

(These are configuration steps that can be taken before you build the application (see above)).

You can configure what modules to use, which database server to use and whether to use test data or not.
Details on how to do custom configurations can be found here: Local configuration instructions.

Step 2 - Run the application

You can test the application quickly by running it with the maven jetty plug-in:

1. In trunk/dhis-2/dhis-web/dhis-web-portal/ type the following command:

   $mvn clean jetty:run-war

2. Open your browser and head to http://localhost:8080 (typically).

Possible configurations

To run the application as a standalone application see Standalone Jetty.
If you want to use Tomcat, see the Tomcat page for instruction.

Optional: Define your database connection

By default DHIS uses an in-memory database server, HSQLDB. This means nothing you do will be saved and each time you (re)start the web server you will get an empty (or populated) database.

If you want to have a database, both MySQL and PostgresSQL has been tested and works with DHIS 2.
For information about using a database see:

• Prepare MySQL for DHIS 2 or
• Prepare PostgresSQL for DHIS 2

Also see the local configuration instruction page for information about changing the database server.

Optional: Quick testing of a single module

If you wish to compile and run a single web module for testing purposes, you may navigate to the web folder's directory and simply clean and run the war file. For example, to run dhis-web-dashboard alone:

1. In trunk/dhis-2/dhis-web/dhis-web-dashboard type the following command:

   $mvn clean jetty:run-war

2. Open your browser and head to http://localhost:8080 (typically).

Optional: Debug with Eclipse

Debugging without a debugger is usually painful, and it isn't obvious how to use a debugger with DHIS 2. Here is an explanation:

_{Source: The official Jetty site}

Step 1: Set up Jetty

Add an environment variable MAVEN_OPTS on your computer with the following value:

-Xdebug -Xnoagent -Djava.compiler=NONE -Xrunjdwp:transport=dt_socket,address=8000,server=y,suspend=n

What if I want to use another application server? Just add the contents of the above environment variable to its command line. This should work for all servers conforming to Sun's servlet spec.

Debugging DHIS 2 startup If there is a problem in DHIS 2's startup routines that you wish to debug, you can get Jetty to pause at startup and wait for you to attach the debugger. Simply replace suspend=n with suspend=y in the above environment variable. Beware, though, that this slows down Jetty dramatically.

Step 2: Configure debugger

1. Pull up the Run -> Debug -> Debug... dialog box.
2. Select Remote Java Application and click the New button. Fill in the fields:
   • In the Project field, select the project whose code you wish to debug.
   • Enter 8000 as the Port number.
   • Check Allow termination of remote VM.

Step 3: Run

If you chose suspend=n in step 1...

1. Start Maven and Jetty. The console should begin with Listening for transport dt_socket at address: 8000.
2. Let Jetty start.
3. When you are ready to start debugging, attach the debugger using Run -> Debug..., selecting your debug configuration.

Note You do not get any feedback that the debugger has attached. However, Eclipse's Debug perspective will display the connected application.

You may now add breakpoints or pause the application in Eclipse's debug perspective.

If you chose suspend=y...

1. Start Maven and Jetty.
2. When you get the console message Listening for transport dt_socket at address: 8000 you may attach the debugger using Run -> Debug..., selecting your debug configuration. In the console, you should see Jetty continuing its startup sequence.

You may now add breakpoints or pause the application in Eclipse's debug perspective.

Stopping Jetty

When you have the Jetty server running and the debugger connected you can switch to the debug perspective. In the debug view, right click on Java HotSpot(TM) Client VM[localhost:8000] and choose Terminate. This will stop the debugger and the Jetty server.

Tips

If you think breakpoints are not working, make sure your code is actually executing. To check this, a good place to put a breakpoint is org.hisp.dhis.security.intercept.WebWorkSecurityInterceptor.intercept(), since this method gets executed for every HTTP call. Then you can step and see if it reaches your code.