DHIS2 Installation Guide for MacOS

by Yongjoon Park, S2HSP/GIZ Nepal


DHIS2 (District Health Information Software) is an open source software platform for reporting, analysis and dissemination of data for all health programmes. It runs on all platforms for which there exists a Java Runtime Environment version 8 or higher, which includes Windows, Linux and of course, MacOS (formerly Mac OS X).

This guide describes how to set up a local server of DHIS2 on MacOS (Sierra) with PostgreSQL as database system and Apache Tomcat as Servlet container. Although the official documentation focuses only on installation on Linux (Ubuntu), there is not much difference between Ubuntu and MacOS in terms of DHIS2 installation. (Actually you can type the same Linux command lines on MacOS thanks to its UNIX-based Bash Shell.) I hope that this guide helps you to install DHIS2 software and a database on your own Mac without programming knowledge.

For the official guide for Ubuntu Linux, please refer to the link here.

You can find a guide for Microsoft Windows from here.

A Mac environment I used for this guide was an early 2015 MacBook Air 13 inch model with 1.6 GHz Intel Core i5 and 8GB RAM. I deployed a DHIS2 version (2.23) of Nepal’s Health Management Information System (HMIS) and its sample live database. Here I ran iTerm2 terminal and VIM text editor. You may also use IDEs such as Eclipse, however how they run a server could be various.

Most software was installed by Homebrew (a package manager for MacOS), so their install location shown here might be different to yours. Personally, I strongly recommend you to use this package manager. It is very convenient and helpful. Visit Homebrew to find out how it can help you.

Step 1. Java (preferably JDK)

  • Install Java Development Kit (JDK) 8

Before installing Java, you can see if it is already installed on your Mac.

$ java -version

Then install the latest Java. If you download and install it from the Oracle website, your JDK will be most likely placed in

  • Set system variables

When you install JDK for the first time, it is not necessary to set system variables like you had to on our familiar Windows. However, if you find other versions of Java as guided above, (i.e. pre-installed Java 6 of some OS X versions) you’d better set $JAVA_HOME variable to the path of specific JDK 8 in your .bash_profile

  • Check the Path
$ echo $PATH
  • Go to the .bash_profile (Otherwise you can create it, too)
$ vim .bash_profile
  • Then set a variable with JDK’s location
export JAVA_HOME=$(/usr/libexec/java_home/)
  • Source it
$ source ~/.bash_profile
  • Confirm the path and JAVA_HOME
$ echo $PATH
$ echo $JAVA_HOME

Step 2. PostgreSQL

  • Install PostgreSQL (Homebrew)

You can install it through either Homebrew or other installers. If installed by Homebrew like me, the location would be /usr/local/var/postgres

  • To run PostgreSQL, you can type
$ postgres -D /usr/local/var/postgres
  • Create a user & database

For more information, consult the official documentation of PostgreSQL.

  • Switch to the default user ‘postgres’

MacOS doesn’t allow us to use $ su postgres

$ sudo su postgres
  • Create a non-privileged user (or Delete it)
$ createuser -SDRP dhis
($ dropuser username)
  • Create a database (or Delete it)
$ createdb -O dhis dhis2
($ dropdb dbname)
  • You can switch to the user you created
$ sudo -u dhis [password]
  • Performance Tuning

Please refer to ‘8.3.5. PostgreSQL performance tuning’ from the documentation. In fact, some of features were not found in my postgresql.conf

Step 3. PgAdmin

  • Install PgAdmin (Homebrew)

This software is an administration and management tool for PostgreSQL. I installed PgAdmin 3 (They recommend version 4 now) through Homebrew Cask. You can also download it from here.

  • Check the user & database

Confirm the users and databases you created after connecting to the server. The biggest difference between Windows and MacOS versions is that the latter has limited functions.

Step 4. Tomcat

  • Install Tomcat 8 (Homebrew)

You can install it through either Homebrew or other installers.

  • Create setenv.sh

Scripts from catalina.sh explains about setting environment variables for Tomcat.

  • Search for path of CATALINA_BASE
$ catalina -h

For me, it was /usr/local/Cellar/tomcat/8.5.4/libexec

  • Create setenv.sh in CATALINA_BASE/bin
$ vim setenv.sh
  • Set environments by adding the lines below
export JAVA_HOME=$(/usr/libexec/java_home/)
export JAVA_OPTS='-Xmx7500m -Xms4000m'
export DHIS2_HOME='/Users/username/dhis/config'

The first line will set the location of your JRE, the second will dedicate memory to Tomcat and the third will set the location for where DHIS2 will search for the dhis.conf configuration file.

  • Source it
$ source setenv.sh
  • Edit server.xml

The Tomcat configuration file is located in CATALINA_BASE/conf. The element which defines the connection to DHIS is the Connector element with port 8080. You can change the port number in the Connector element to a desired port if necessary. If UTF-8 encoding of request data is needed, make sure that the URIEncoding attribute is set to UTF-8.

<Connector port="8080" protocol="HTTP/1.1"
   URIEncoding="UTF-8" />

Step 5. DHIS2 & Configuration

  • Create a folder

I created /Users/username/dhis/config

  • Create dhis.conf

In accordance with variables set by Tomcat’s setenv.sh, DHIS2 will refer to the configuration to connect a server.

# Hibernate SQL dialect
connection.dialect = org.hibernate.dialect.PostgreSQLDialect
# JDBC driver class
connection.driver_class = org.postgresql.Driver
# Database connection URL
connection.url = jdbc:postgresql:dhis2
# Database username
connection.username = dhis
# Database password
connection.password = xxxx
# Database schema behavior, can be validate, update, create, create-drop
connection.schema = update
# Encryption password (sensitive)
encryption.password = xxxx

Step 6. Ready for Deployment

  • Put WAR file in webapps folder

For me, it was


Step 7. Run PostgreSQL

  • Run it
$ postgres -D /usr/local/var/postgres

You may want to use a gem called ‘lunchy’ to easily start and stop Postgres. Refer to the following link.

  • Import a sql file using psql command
$ psql -d <dbname> -U <username> -f <sql path>

It might take a time depending on the size of the database.

Step 8. Run Tomcat & Deploy WAR

$ catalina run         // Start in the current window
$ catalina start       // Start in a separate window
$ catalina stop        // Stop the running server

Hit the command, then tomcat server will start up DHIS2 by deploying WAR file. Pay attention to Tomcat logs especially when something seems to go wrong.

Step 9. Access DHIS2 by Localhost

Assuming that your WAR is called ‘dhis’, you will access your local DHIS2 by this URL.


Step 10. Confirmation of Installation Details

After launching the DHIS2 and signing in, Go to ‘About DHIS2’. You will see the installation details.