Installing DHIS 2 - DHIS Documentation

Installation options

The packaged installers have relatively lax security and are only meant for installations on desktops, not servers. If you need to run different instances of DHIS 2 concurrently on the same machine (e.g. on a server), you need to compile each of them with different values for DHIS2_HOME and OPENHEALTH_HOME.
Details on the installer

Installing

On a machine without DHIS2, the installer will ask you for the directory path where DHIS 2 is to be installed. This path cannot have spaces (e.g. you cannot install in C:\Program Files). It will then proceed to install the database engine (PostgreSql), Java (SDK), and a servlet container (Tomcat) which includes components for reporting (birt.war) and maps (geoserver.war).

All files for installation or upgrading should be placed in one folder.

Database and other file upgrades

Upgrading

2) Create your own installer

As new versions of DHIS 2 become available or you want to distribute real datasets in addition to the sample data, you can easily compile your own installers. Get BitRock (free for use for the BSD licensed DHIS 2. Contact Øystein: oysts AT ifi.uio.no for our license for BitRock)

Start from this script, and use the files that are created after you run one of the ready-made installers above (of course, you can replace the .war files or database files etc.)

3) Manual step-by-step installation

Instructions for pre-packaged versions, which can be downloaded from the Downloads page.

Here's an overview of the required software in order to run and use DHIS 2:

Java Runtime Edition (JRE) version 5 or later
A database management system (DBMS), typically MySQL, PostgreSQL or HSQLDB (HSQLDB is included with DHIS 2, see below)
A servlet container/web server, typically Jetty or Tomcat
DHIS 2

How to install and configure a web browser and the JRE is not covered by this document, and must be completed before proceeding with the installation.

Installation steps covered by this document:

Step 1 - Installing a DBMS
Step 2 - Configuring DHIS 2 to use the DBMS
Step 3 - Installing a servlet container/web server

Step 1 - Installing a DBMS

By default, DHIS 2 will use and in-memory HSQLDB database which is already packaged with DHIS 2. This is useful for testing and demonstration purposes when there is no need for keeping the data between runs. However, the initial data in the database is limited to what the selected version of DHIS 2 provides. If this is the desired behaviour, skip forward to Step 3 - Installing a servlet container/web server.

DHIS 2 uses a database abstraction framework which allows DHIS 2 to work with many different DBMSs (see SQL Dialects in the Hibernate documentation for a list of theoretically supported DBMSs]. However, MySQL and PostgreSQL have been selected for direct support by DHIS 2, and are described in this document. If any other DBMS is prefered, a suitable connection driver must be provided, as connection drivers for only MySQL and PostgreSQL are packaged with DHIS 2.

Please continue with one of the following:

Installing MySQL
Installing PostgreSQL

Installing MySQL

For Windows and Linux

MySQL downloads page: http://dev.mysql.com/downloads
MySQL documentation: http://dev.mysql.com/doc/

Download MySQL from the MySQL downloads page
Unpack/install and follow the instructions as described in the MySQL documentation: http://dev.mysql.com/doc/refman/5.1/en/installing.html
In your MySQL configuration file (my.ini on Windows, /etc/mysql/my.cnf on Linux) make sure the database type is set to INNODB and the default character set is set to utf-8. In the [mysqld] section, add if necessary:

default-storage-engine=INNODB
default-character-set=utf8

The values can be confirmed by entering "SHOW VARIABLES" in the MySQL command line client.

Log on to the MySQL command line client (> mysql -u root) and issue the following commands to create an accessible DHIS 2 database:

mysql> create database dhis2 default character set utf8 collate utf8_general_ci;
mysql> grant all on dhis2.* to dhis@"localhost" identified by '';

Start MySQL. Windows users can choose between the following ways:
- Command line: Open DOS prompt (Start menu -> Run, type "cmd" and click OK). Navigate to the mysql/bin directory and execute
```
> mysqld-nt --console
```
  (on an older version of Windows, use mysqld instead of mysqld-nt). The following command will stop MySQL if you wish:
```
> mysqladmin shutdown
```
- System service: Making MySQL a system service will make MySQL automatically start when Windows starts. Follow the same procedure as with the command line, except instead execute
```
> mysqld-nt -install
```
  Start the service by issuing
```
> NET START MYSQL
```
  The following command will stop MySQL if you wish:
```
> NET STOP MYSQSL
```

Now continue with Step 2 - Configuring DHIS 2 to use the DBMS

For Mac

Binary packages can be found at http://www.mysql.org/downloads/mysql/5.0.html#downloads
Instructions can be found at http://www.entropy.ch/software/MacOSx/mysql/
Administration GUI can be found at http://cocoamysql.sourceforge.net/

Installing PostgreSQL

PostgreSQL downloads page: http://www.postgresql.org/download/
PostgreSQL documentation: http://www.postgresql.org/docs/

For Windows

Download PostgreSQL from the downloads page
Start the installation by executing the downloaded installer
Follow the instructions and name your user dhis when asked
When done, select Start menu -> All Programs -> PostgreSQL [version] -> pgAdmin III (pgAdmin documentation: http://www.pgadmin.org)
In pgAdmin connect to your database server, by default named PostgreSQL Database Server [version]. You will be asked for a password which is the one you entered for the user at the installation of PostgreSQL.
Right-click on databases -> New database. Name your database dhis2, and the owner of the database dhis
Go to Start menu -> All Programs -> PostgreSQL [version] and click on Start Service

For Linux

Switch user to postgres (> [sudo] su postgres)

Start the PostgreSQL client (> psql) and issue the following:

postgres=# create user dhis with password '';
postgres=# create database dhis2 with owner dhis;

Quit and return to your standard user

If you have authentication problems you might have to make the following changes in /etc/postgres/[version]/main/pg_hba.conf:

# Replace:
local   all         all                               ident sameuser
# with:
local   all         all                               trust
# or, if you use passwords:
local   all         all                               md5

For Mac

Binary packages and instructions can be found at http://www.entropy.ch/software/macosx/postgresql/
A guide on how to compile it yourself can be found at http://developer.apple.com/internet/opensource/postgres.html
Install the StartupItem package from http://www.entropy.ch/software/macosx/postgresql/
Create a database called dhis2 with dhis as the owning user, and start PostgreSQL

Step 2 - Configuring DHIS 2 to use the DBMS

You should now create an environment variable called DHIS2_HOME (In Windows, right-click on My Computer and choose "Properties". In the box that opens, click the "Advanced" tab, and then on the button "Environment Variables". There, add a DHIS2_HOME variable with the full path to <YOUR INSTALL DIR>/config.
(Help )

Create a hibernate.properties file in this folder. The contents of this file depend on which DBMS you have installed and how it is configured. Alternatively, if you are using tomcat as your webapp server (see below), you can place the hibernate.properties file in ''your-tomcat-folder\lib'' (typically ''c:\Program Files\Apache Tomcat 6.0.14\lib'' on windows etc.).

Typical contents of hibernate.properties when using MySQL:

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 =
hibernate.hbm2ddl.auto = update

Typical contents of hibernate.properties when using PostgreSQL:

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 =
hibernate.hbm2ddl.auto = update

Note that you might need to change the username, password and/or the name of the database to match your configuration. In both examples over the database name is dhis2, located in the hibernate.connection.url.

Also note that if you intend to use the demonstration version of DHIS 2, which inserts data into the database every time the system is started, you will have to change the hibernate.hbm2ddl.auto from update to create-drop. This will make the system empty the whole database before adding the demonstration data upon start. If the hibernate.hbm2ddl.auto is not changed, all but the first run of DHIS 2 will fail because of duplicate entries in the database.

Step 3 - Installing a servlet container/web server

Using Tomcat

Download Tomcat server at http://tomcat.apache.org/download-55.cgi. You can use the installation package or binary package.
Install Tomcat on your computer (Note : Make sure there are no space between the words of the path).
Copy the pre-packaged .war file into Tomcat's webapps folder (tomcat\webapps).
Start and Stop tomcat
Double click tomcat5w.exe file in bin folder (tomcat\bin).
4.1 Start tomcat : Chose Start button to start service for running application.
4.2 Stop tomcat : Chose Stop button to stop service when finished application.
Run DHIS 2.0
Direct your web browser to http://localhost:8080/dhis/ where dhis is the name of the pre-packaged .war file.

For more information see the Tomcat page.

Running DHIS 2

In the DHIS2 folder, click on start.bat. Two MS-DOS command windows will open.
The first time, you have to click Unblock for mysql-nt and then Java.
Leave the two command windows open. (One runs the MySql database, the other runs the Jetty server with the DHIS 2 application). Startup will take some time, and is done when you see the following in the front command window:
```
Started SelectChannelConnector @ 0.0.0.0:8080
```
Open your browser (Firefox 2 is recommended), and type the following in the address field:
```
localhost:8080
```
After some time, you will see the Welcome page. Make a bookmark.
Log in as "hisp", password "hisp". Or use "admin"/"district"
To stop DHIS 2, click on stop.bat in the same folder

Hints

To find out if you have Java 1.5 installed already, click on Start -> Run, type "cmd". In the new window, type "java -version"

For changing to a different database, unzip this small configuration file (2kb) in your USER_HOME directory Help and edit the hibernate.properties file according to your setup.

Table of contents