Community Blog Deploy DHIS2 on Alibaba Cloud ECS Instance

Deploy DHIS2 on Alibaba Cloud ECS Instance

In this tutorial, we will explain how to get DHIS2 up and running on an Alibaba Cloud Elastic Compute Service (ECS) instance with Ubuntu 16.04.

By Erick Otenyo, Alibaba Cloud Tech Share Author. Tech Share is Alibaba Cloud's incentive program to encourage the sharing of technical knowledge and best practices within the cloud community.

DHIS2 is a tool for collection, validation, analysis, and presentation of aggregate and patient-based statistical data, tailored to integrated health information management activities. It is a generic tool rather than a pre-configured database application, with an open meta-data model and a flexible user interface that allows the user to design the contents of a specific information system without the need for programming.

The DHIS2 database is designed ground-up with flexibility in mind. Data structures such as data elements, organisation units, forms and user roles can be defined completely freely through the application user interface. This makes it possible to adapt the system to a multitude of locale contexts and use cases that require routine data capture and analysis. This has allowed for DHIS2 to serve as management system in different domains such as logistics, labs and finance.

DHIS2 is an open source software under the BSD licence and thus can be obtained freely and run on any platform with a Java Runtime Environment installed.

The following are the key features and purpose of DHIS2

  • DHIS2 provides a comprehensive data management solution based on data warehousing principles and a modular structure which can easily be customised to the different requirements of a management information system, supporting analysis at different levels of the organisational hierarchy.
  • Customisation and local adaptation through the user interface. Setting up and configuring DHIS2 doesn not require programming.
  • Provides data entry tools which can either be in the form of standard lists or tables, or can be customised to replicate paper forms.
  • Flexible and dynamic data analysis in the analytics modules (i.e. GIS Maps, PivotTables,Data Visualizer, Event reports, etc).
  • Easy to use user-interfaces for metadata management e.g. for adding/editing datasets or health facilities. No programming needed to set up the system in a new setting
  • A user-specific dashboard for quick access to the relevant monitoring and evaluation tools including indicator charts and links to favourite reports, maps and other key resources in the system.

A typical informaton cycle in a DHIS2 system icludes:

  1. Data collection
  2. Data quality checks and validation
  3. Data access at multiple security levels
  4. Reporting
  5. Visualizing data with graphs, pivot tables and maps
  6. Comparison of data across time, different organisation units (facilites in health)
  7. Visualizing trends in a time series analysis

In this tutorial, we will be covering on how to get DHIS2 up and running on an Alibaba Cloud Elastic Compute Service (ECS) Ubuntu 16.04 instance.


Before we deploy our DHIS2 instance, we need to fulfill the following requirements. We need to set up an Alibaba Cloud Elastic Compute Service (ECS) Linux server (Ubuntu 16.04) with atleast 4GB of RAM and basic configurations. You should also allocate administrator (sudo) privileges to a non-root user.

You can refer to this guide for setting up your Alibaba Cloud ECS instance. If you don't have an Alibaba Cloud account, you can sign up for free and enjoy $300 worth in Free Trial.

Deploying DHIS2 on Ubuntu 16.04 ECS Instance

To deploy DHIS2 on our server, we will first need to install a few requirements and configure the Java Runtime Environment neccessary for DHIS2 to run.

We will need to install a Postgres/PostGIS database and thereafter install Java and setup the configurations.

Step 1: Setting Server Time Zone

It may be important to match the server timezone with the location which the DHIS2 server will be covering. The default time zone on the ECS instance may not correspond to the time zone of your DHIS2 location. To reconfigure the timezone, invoke the command below and follow the instructions displayed:

sudo dpkg-reconfigure tzdata

Step 2: Creating an Ubuntu User to Run DHIS2

The DHIS2 server should not be run as a privileged user such as root. Therefore create a new dedicated user for running DHIS by invoking:

sudo useradd -d /home/dhis -m dhis -s /bin/false

Then set the password for the account by invoking:

sudo passwd dhis

Make sure you set a strong password

Step 3: Creating the Configuration Directory

Create a suitable directory for the DHIS2 configuration files that will also be used for apps in DHIS2, files and log files

sudo mkdir /home/dhis/config

Set ownership of the directory to 'dhis' user created above

sudo chown dhis:dhis /home/dhis/config

Step 4: PostgreSQL Installation and Tuning

Install PostgreSQL and the PostGIS extension by invoking:

sudo apt-get install postgresql-9.5 postgresql-contrib-9.5 postgresql-9.5-postgis-2.2

Create a non-privileged PostgreSQL user called 'dhis' by invoking:

sudo -u postgres createuser -SDRP dhis

Give a password for the new PostgreSQL user when prompted.

Create a database that will be used by the DHIS2 instance by invoking:

sudo -u postgres createdb -O dhis dhis2

The PostGIS extension is needed for several GIS/mapping features to work. Create the PostGIS extension by invoking:

sudo -u postgres psql -c "create extension postgis;" dhis2

PostgreSQL performance tuning is necesarry to achieve a high performing system in a production environment. Note this is not neccessary in terms of getting DHIS2 to run.

Open the postgresql.conf file for editing:

sudo nano /etc/postgresql/9.5/main/postgresql.conf

Set the following properties:

max_connections = 200
shared_buffers = 3200MB
work_mem = 20MB
maintenance_work_mem = 512MB
effective_cache_size = 8000MB
checkpoint_completion_target = 0.8
synchronous_commit = off
wal_writer_delay = 10000ms

For an indepth explanation of the above properties, please refer the DHIS2 docs

Step 5: Creating DHIS2 Configuration File

The database connection information is provided to DHIS2 through a configuration file called dhis.conf. Create this file and save it in the configuration directory we created in Step 3:

sudo -u dhis nano /home/dhis/config/dhis.conf

Insert following lines to the file (update PostgreSQL dhis user password according what you set above):

# 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: Java Installation

Oracle Java will need to be installed manually. Create a directory to install Java:

mkdir /usr/java/
cd /usr/java/

Next we need to download oracle java from the Java download page.

Obtain the correct download link with 'Linux x64' from the above link and replace http://oracle-java-download-link in the command below with that link. It should look something like http://javadl.oracle.com/webapps/download/AutoDL?BundleId=235717_2787e4a523244c269598db4e85c51e0c

wget -O java-linux-x64.tar.gz http://oracle-java-download-link

After downloading, untar by invoking the following:

tar zxvf java-linux-x64.tar.gz

Step 7: Tomcat Installation

To install the Tomcat servlet container we will utilize the Tomcat user package. This lets us easily create a new Tomcat instance. Install the package by invoking:

sudo apt-get install tomcat7-user

To create a Tomcat instance for DHIS2 move to the dhis folder created earlier:

cd /home/dhis/

Create Tomcat instance:

sudo tomcat7-instance-create tomcat-dhis

Set ownership of the created folder to dhis user

sudo chown -R dhis:dhis /home/dhis/tomcat-dhis/

Edit setenv.sh:

sudo nano /home/dhis/tomcat-dhis/bin/setenv.sh

Add the following lines to the bottom of the file:

Please note that jre1.8.0_191 directory as below may change according to oracle java version downloaded.

export JAVA_HOME='/usr/java/jre1.8.0_191/'
export JAVA_OPTS='-Xmx2000m -Xms1000m'
export DHIS2_HOME='/home/dhis/config'

Step 8: DHIS Installation

The next step is to now download the DHIS2 WAR file and place it into the webapps directory of Tomcat.

You can download the DHIS2 version 2.30 WAR release as below (replace 2.30 with your preferred version if necessary):

wget https://s3-eu-west-1.amazonaws.com/releases.dhis2.org/2.30/dhis.war

Move the WAR file into the Tomcat webapps directory. We want to call the WAR file ROOT.war in order to make it available at localhost directly without a context path:

sudo mv dhis.war tomcat-dhis/webapps/ROOT.war

DHIS2 should never be run as a privileged user, so edit the startup.sh to use the dhis user we created earlier:

sudo nano /home/dhis/tomcat-dhis/bin/startup.sh

Replace everything in the file with the following lines:

set -e

if [ "$(id -u)" -eq "0" ]; then
   echo "This script must NOT be run as root" 1>&2
   exit 1

export CATALINA_BASE="/home/dhis/tomcat-dhis"
echo "Tomcat started"

Step 10: Running DHIS2

DHIS2 can now be started by invoking:

sudo -u dhis tomcat-dhis/bin/startup.sh

To monitor the behavior of Tomcat, the log is the primary source of information. The log can be viewed with the following command:

tail -f tomcat-dhis/logs/catalina.out

Assuming that the WAR file is called ROOT.war, you can now access your DHIS2 instance at:


The Default login details are:

Username: admin
Password: district

DHIS2 can be stopped by invoking:

sudo -u dhis tomcat-dhis/bin/shutdown.sh

Step 11: Starting DHIS2 at Server Startup

In certain situations the server might reboot unexpectedly. It is preferable to have Tomcat start automatically when the server starts. To achieve that the first step is to create init scripts.

Create init scripts:

sudo nano tomcat

Enter the following lines:

#Tomcat init script


case $1 in
   sudo -u dhis ${HOME}/startup.sh
   sudo -u dhis ${HOME}/shutdown.sh
   sudo -u dhis ${HOME}/shutdown.sh
   sleep 5
   sudo -u dhis ${HOME}/startup.sh
exit 0

Move the script to the init script directory and make it executable by invoking:

sudo mv tomcat /etc/init.d
sudo chmod +x /etc/init.d/tomcat

Next make sure the tomcat init script will be invoked during system startup and shutdown:

sudo /usr/sbin/update-rc.d -f tomcat defaults 81

Tomcat will now be started at system startup and stopped at system shutdown. If you later need to revert this you can replace defaults with remove and invoke the above commands again


Hooray ! If you were able to follow this tutorial up to this point, your DHIS2 instance should be up and running on your Alibaba Cloud Elastic Compute Service (ECS) Instance. We have done a basic setup to get us started with our DHIS2 server, but you might need further customization for DHIS2 to work as per your use case, mainly from the admin user interface. For that and more, you can refer to the official documentantion of DHIS2, which covers all the DHIS2 platform instructions in detail.

0 0 0
Share on

Alibaba Clouder

1,940 posts | 433 followers

You may also like


Alibaba Clouder

1,940 posts | 433 followers

Related Products