This information might not be up to date.

Local configuration instructions

Change the database server
Configure which modules (functionality) to use in your application
Automatically populate your database at application start-up

Change the database server

The database server can easily be changed by changing the hibernate configuration file and adding a dependency to the necessary database driver in the dhis-support-hibernate project.
Note that the application does not have to be compiled and rebuilt to include changes to hibernate.properties, but you need to restart the application (e.g. stop and start Jetty).

General steps:
1. Add and/or modify the hibernate.properties file in <USER_HOME>/dhis/
The hibernate.properties file contains the information needed by hibernate to connect and use your favourite database server.
There is already defined a default configuration file:
dhis-2/dhis-support/dhis-support-hibernate/src/main/resources/hibernate-default.properties
It looks like this:

hibernate.show_sql = false
hibernate.use_sql_comments = false
hibernate.dialect = org.hibernate.dialect.HSQLDialect
hibernate.connection.driver_class = org.hsqldb.jdbcDriver
hibernate.connection.url = jdbc:hsqldb:.
hibernate.connection.username = sa
hibernate.connection.password =
hibernate.connection.pool_size = 10
hibernate.hbm2ddl.auto = create-drop

#hibernate.dialect = org.hibernate.dialect.MySQLDialect
#hibernate.connection.driver_class = com.mysql.jdbc.Driver
#hibernate.connection.url = jdbc:mysql://localhost/dhis2?useUnicode=true&characterEncoding=UTF-8

#hibernate.dialect = org.hibernate.dialect.PostgreSQLDialect
#hibernate.connection.driver_class = org.postgresql.Driver
#hibernate.connection.url = jdbc:postgresql:dhis2

This file MUST NOT BE CHANGED.

In stead, to define your own database connection by creating a new file called hibernate.properties and put it in:
<USER_HOME>/dhis/.

This custom configuration file will overwrite the settings already defined in the default file above.

In the default file you will se the necessary settings needed for a MySQL and a PostgreSQL connection. These lines are commented out by the '#' symbol.
Copy the lines you need and paste them in your local file, and remember to remove the #. Note that you also will need to put the password and username settings in your local file, if these are different from the default file (see above). Furthermore, in the usual scenario you should create a database and run a setup script to setup the database structure before you start up the DHIS 2.0 application. This means that you have to change the hibernate.hbm2ddl.auto setting as well. The default setting that can be seen above is "create-drop" which first deletes the existing database and then creates the database structure at application start-up, which is nice for testing purposes , but not for production use. So, in your local file you must add the line hibernate.hbm2ddl.auto = validate which only validates the structure at start-up and keeps it after shutdown. If you don't have this line the default (create-drop) will be used and your data will be lost.

For other databases than MySQL and PostgreSQL we ask you kindly to read the hibernate documentation covering database (JDBC) connections. Feel free to add examples here on how to set up DHIS 2.0 with other database servers.

Example of a local file <USER_HOME>/dhis/hibernate.properties based on the following conditions:

use MySQL
database name "dhis2"
username "dhis"
password "hisp"
support for unicode (utf8)
the database structure is already created (a database setup script must be run before you can start up the DHIS 2.0 application)

hibernate.dialect = org.hibernate.dialect.MySQLDialect
hibernate.connection.driver_class = com.mysql.jdbc.Driver
hibernate.connection.url = jdbc:mysql://localhost/dhis2?useUnicode=true&characterEncoding=UTF-8
hibernate.connection.username = dhis
hibernate.connection.password = hisp
hibernate.hbm2ddl.auto = validate

2. Add a dependency to the database driver in the dhis-support-hibernate project
Our build tool maven must be told where to find the driver needed to connect to the database (the one defined in hibernate.properties) and this can be done in the dhis-support-hibernate's pom.xml file:
dhis-2/dhis-support/dhis-support-hibernate/pom.xml

Here is the part of the pom.xml file that defines the database driver that are already defined:

<!-- hsqldb -->
    <dependency>
      <groupId>hsqldb</groupId>
      <artifactId>hsqldb</artifactId>
    </dependency>

    <!-- MySQL -->
    <dependency>
      <groupId>mysql</groupId>
      <artifactId>mysql-connector-java</artifactId>
      <version>3.1.11</version>
    </dependency>

    <!-- PostgreSQL -->
    <dependency>
      <groupId>postgresql</groupId>
      <artifactId>postgresql</artifactId>
      <version>7.4.1-jdbc3</version>
    </dependency>

To find your driver information please read documentation at the webpage of the database server of your choice and look for JDBC drivers. You can then search www.ibiblio.org for the driver (search for the name of the jar file) to get information needed for the dependency configuration (groupId, artifactId, version).

Configure which modules (functionality) to use in your application

The dhis-web-portal project provides a framework for a modularised user interface were modules or functionality if you like easily can be included or excluded in your locally configured application. See the The DHIS 2.0 web solution page for detailed information on how to do this.

Example - Configure the application to use the Kerala web reports module

(this module is already set up to be compatible with the DHIS 2.0 web portal, but is not included in the application by default)

Step 1 - Build the dhis-2 project
Make sure you build the version you want, either the released versions in tags/ or the "in-development" code in trunk/dhis-2/
Information on the released versions are found here:
DHIS 2.0 Home page

Step 2 - Configure the Kerala web reports module to use the correct version of the dhis-2 core modules (the dhis-2 project):
The module (or more correctly speaking, the project) is located in scm/sandbox/dhis-web-reports.

Short version:
So to make sure the dhis-web-reports project is compatible with the rest of the application make sure that the dhis-web version in the parent declaration is correct. All other projects/modules that will be part of your web application (dhis-web-portal) will also use dhis-web as their parent, so if they all use the same version of dhis-web, then the whole application will be consistent and able to build

Long version:
The configuration is done in the file scm/sandbox/dhis-web-reports/pom.xml
The dependency declarations ( <dependency> project info </dependency>) tells which other projects your project is dependent on, what you need to build your project, in this case the Kerala reports module. The project info within the <dependency> declarations must contain a groupId, an artifactId and a version. To simplify the task of keeping track of the right versions used across many DHIS projects we use a parent project that decides the versions for all "child" projects configuration files. The dhis-web-reports project has the following parent declaration in its pom.xml file:

<parent>
   <groupId>org.hisp.dhis</groupId>
   <artifactId>dhis-web</artifactId>
   <version>2.0-M4-SNAPSHOT</version>
 </parent>

Further down in the file the following dependencies on other DHIS projects:

<dependency>
      <groupId>org.hisp.dhis</groupId>
      <artifactId>dhis-core-dhis2</artifactId>
    </dependency>

    <dependency>
      <groupId>org.hisp.dhis</groupId>
      <artifactId>dhis-support-test</artifactId>
    </dependency>

    <dependency>
      <groupId>org.hisp.dhis</groupId>
      <artifactId>dhis-support-webwork</artifactId>
    </dependency>

    <dependency>
      <groupId>org.hisp.dhis</groupId>
      <artifactId>dhis-service-organizationstore-hibernate</artifactId>
    </dependency>

    <dependency>
      <groupId>org.hisp.dhis</groupId>
      <artifactId>dhis-web-commons</artifactId>
    </dependency>

As you can see the version is not mentioned here, because the versions are given in the pom.xml file of the dhis-web project.

The dependency declarations are used by maven when you build a project, and all the dependencies are references to packaged projects (.jar or .war files) that maven keep in its local repository (in windows this is normally C:\Documents and Settings\<username>\.m2\repository). When you build a project the project is packaged into either a jar file or a war file (based on the pom.xml configuration, war files are web projects), and put into the maven repository. So when you want to build the dhis-web-reports project and it is dependent on the dhis-2/dhis-core-dhis-2 project you must first build the dhis-2 project (and automatically all its sub projects) in order to have the jar file of dhis-core-dhis-2 available in your maven repository. That is why the order of which you build the different project is so important.

So to make sure the dhis-web-reports project is compatible with the rest of the application make sure that the dhis-web version in the parent declaration is correct. All other projects/modules that will be part of your web application (dhis-web-portal) will also use dhis-web as their parent, so if they all use the same version of dhis-web, then the whole application will be consistent and able to build

Step 3 - Build the Kerala web reports module

In sandbox/dhis-web-reports/
$mvn clean install

Step 4 - Configure the web portal to include the Kerala web reports module
Which projects (or modules if you like) that will be part of the web application (the web portal) is configured in dhis-web-portal?s pom.xml file.
So look up the version of DHIS you want and then look for the file dhis-2/dhis-web/dhis-web-portal/pom.xml

The following code tells which projects that should be included:

<warArtifacts>
                <!--
                <warArtifact>
                  <groupId>org.hisp.dhis</groupId>
                  <artifactId>...</artifactId>
                  <version>2.0-M4-SNAPSHOT</version>
                </warArtifact>
                -->
                <warArtifact>
                  <groupId>org.hisp.dhis</groupId>
                  <artifactId>dhis-web-maintenance-datadictionary</artifactId>
                  <version>2.0-M4-SNAPSHOT</version>
                </warArtifact>
                <warArtifact>
                  <groupId>org.hisp.dhis</groupId>
                  <artifactId>dhis-web-maintenance-dataset</artifactId>
                  <version>2.0-M4-SNAPSHOT</version>
                </warArtifact>
                <warArtifact>
                  <groupId>org.hisp.dhis</groupId>
                  <artifactId>dhis-web-dataentry</artifactId>
                  <version>2.0-M4-SNAPSHOT</version>
                </warArtifact>
                <warArtifact>
                  <groupId>org.hisp.dhis</groupId>
                  <artifactId>dhis-web-maintenance-organizationunit</artifactId>
                  <version>2.0-M4-SNAPSHOT</version>
                </warArtifact>
            
		    <warArtifact>
                  <groupId>org.hisp.dhis</groupId>
                  <artifactId>dhis-web-reports</artifactId>
                  <version>2.0-M4-SNAPSHOT</version>
                </warArtifact>
		
                <warArtifact>
                  <groupId>org.hisp.dhis</groupId>
                  <artifactId>dhis-web-reporttool</artifactId>
                  <version>2.0-M4-SNAPSHOT</version>
                </warArtifact>
                <warArtifact>
                  <groupId>org.hisp.dhis</groupId>
                  <artifactId>dhis-web-importexport</artifactId>
                  <version>2.0-M4-SNAPSHOT</version>
                </warArtifact>
              </warArtifacts>

Note that the text between the <!?and? is commented out and not part of the configuration. So the first artefact is a template to follow.

Each war artefact is a web-based project that you want to include in your portal application. The artifactId and versionId must match the ones you have defined in the pom.xml of your project. In this case the dhis-web-reports has the same version number as the parent, which is the dhis-web project. If you look at the pom.xml of the dhis-web project you will see that it also has the same version as its own parent which is the dhis-2 project. This is done to reduce the number of conflicting version. So when checking the version of the dhis-2 project?s (in dhis-2/pom.xml) you will see:

<groupId>org.hisp.dhis</groupId>
  <artifactId>dhis</artifactId>
  <version>2.0-M4-SNAPSHOT</version>

So the version that should be used for dhis-web-reports in the war artefact declaration in the pom.xml of dhis-web-portal is the same as the version of the dhis-2 project that you use, basically the version of your release (right now: 2.0-M1, 2.0-M2, 2.0-M3, or 2.0-M4-SNAPSHOT).

Step 5 - Build the web portal
No that you have built all the projects and its dependencies and configured the web portal it is time to build the portal itself, in dhis-2/dhis-web/dhis-web-portal/

$mvn clean package

Step 6 - Run the web portal
To run the portal with the maven jetty plugin:

$mvn clean jetty:run-war

Automatically populate your database at application start-up

Using the dhis-populator project you can populate the application's database with start-up data. This is often useful for testing or when you want to populate a new database from an external source without using a database client directly.

How to use the dhis-populator:
1. Include a dependency to the dhis-populator project in dhis-2/dhis-web/pom.xml
Tell the dhis-web (common configuration for all web modules (inside dhis-web/)) to use the dhis-populator project and where to find it by adding the following lines to it's pom.xml:

<dependencies>
    <dependency>
      <groupId>org.hisp.dhis</groupId>
      <artifactId>dhis-populator</artifactId>
      <version>2.0-M3-SNAPSHOT</version>
    </dependency>
  </dependencies>

And when you do not want to use the populator (you already have a database populated and running) just make sure these lines are removed.

2. Specify what data that is going to be populated into the database
The file dhis-2/dhis-populator/src/main/resources/populator.dat controls what is going to be populated into the database at application start-up.
Modify the text-based file using your favourite text-editor.