You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 5 Current »

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:

    🌐 Accessing DHIS2

    Once Tomcat starts, access your instance at:

    http://<your-server-ip>:8080

Default Login Credentials

  • Username: admin

  • Password: district


  • No labels