View Source

DHIS2 (District Health Information Software 2) is an open-source platform used for health information systems. In this guide,

we'll walk you through installing DHIS2 version v40.3.0 on a server running Ubuntu 22.04.

✅ Prerequisites

A server running Ubuntu 22.04
SSH access to the server with a non-root user that has sudo privileges
At least 8 GB RAM and 2 CPUs (recommended for production)

Step 1: Create a Dedicated DHIS2 User

We'll begin by creating a system user for running DHIS2:

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

🔐 Use a strong password with at least 15 random characters.

Step 2: Set Up DHIS2 Configuration Directory

Create a directory for DHIS2 configuration, logs, and app files:

sudo -u dhis mkdir /home/dhis/config

Set your system timezone (recommended for logging and DB timestamps):

sudo dpkg-reconfigure tzdata

Choose: Asia/Kolkata

PostgreSQL installation

Step 3: Install PostgreSQL 16 with Required Extensions

Add PostgreSQL repository

sudo sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list'

Import the PostgreSQL repository signing key:

curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc|sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/postgresql.gpg

Update the package lists

sudo apt update -y && sudo apt upgrade -y

Install PostgreSQL 16

sudo apt-get install -y postgresql-16 postgresql-16-postgis-3

Ensure postgresql is started and enabled

sudo systemctl start postgresql
sudo systemctl enable postgresql

Create a non-privileged database user dhis with the command below:
```
sudo -u postgres createuser -SDRP dhis
```
Enter a secure password at the prompt:

Create a database named dhis owned by dhis database user by invoking:
```
sudo -u postgres createdb -O dhis dhis;
```
Since DHIS2 database user does not have permission to create extensions, create them from the console using the postgres user with the following commands:
sudo -u postgres psql -c "create extension postgis;" dhis
sudo -u postgres psql -c "create extension btree_gin;" dhis
sudo -u postgres psql -c "create extension pg_trgm;" dhis

Java installation

Step4: Install JAVA by following below steps

The recommended Java JDK for DHIS2 2.40 and above is OpenJDK 17, its required for 2.41.

sudo apt-get install -y openjdk-17-jdk

Verify that your installation :

java -version

DHIS2 configuration

Step5: Install DHIS2 by following below steps

Create dhis.conf file and edit.

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

# ----------------------------------------------------------------------
# Database connection
# ----------------------------------------------------------------------

# JDBC driver class
connection.driver_class = org.postgresql.Driver

# Database connection URL
connection.url = jdbc:postgresql:dhis

# Database username
connection.username = dhis

# Database password
connection.password = xxxx

Tomcat installation

Step6:To install the Tomcat servlet container we will utilize the Tomcat user Install it with below command,

sudo apt-get install -y tomcat9-user

Use below command to create an instance named tomcat-dhis in /home/dhis/tomcat-dhis directory

sudo tomcat9-instance-create /home/dhis/tomcat-dhis
sudo chown -R dhis:dhis /home/dhis/tomcat-dhis/

Edit the file setenv.sh:

sudo -u dhis vim /home/dhis/tomcat-dhis/bin/setenv.sh

export JAVA_HOME='/usr/lib/jvm/java-17-openjdk-amd64/'
export JAVA_OPTS='-Xms3g -Xmx6g'
export DHIS2_HOME='/home/dhis/config'


Edit the file startup.sh:

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

#!/bin/sh
set -e

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

export CATALINA_BASE="/home/dhis/tomcat-dhis"
/usr/share/tomcat9/bin/startup.sh
echo "Tomcat started"

Step7: download dhis2 version v40.3.0

wget -O dhis.war https://releases.dhis2.org/40/dhis2-stable-40.3.0.war

Move the WAR file into the Tomcat webapps directory. 

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

Running DHIS2

Step8: Start DHIS2

Start the DHIS2 instance with the command below:

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

Check the logs live:

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

To stop the DHIS2 instance:

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

If the WAR file deployed in webapps is named ROOT.war, you can now access your DHIS2 instance at the following URL:
http://<your-server-private-ip>:8080

Default Login Credentials

Username: admin
Password: district