Prerequisites

• Server running Ubuntu 22.04
• SSH Access with non-root user with sudo privileges

Step1: Create a dhis2 system user

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

Set the password for the created user

sudo passwd dhis

Make sure you set a strong password with at least 15 random characters.

Step2: Create config directory for the DHIS2 instance. This directory will also be used for apps, files and log files.

sudo -u dhis mkdir /home/dhis/config

sudo dpkg-reconfigure tzdata

Set timezone to Asia/Kolkata

PostgreSQL installation

Install PostgreSQL with below steps

• 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

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 is correct by invoking:

java -version

DHIS2 configuration

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 and DHIS2 installation

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: 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'

DHIS2 should never be run as a privileged user. After you have modified the setenv.sh file, modify the startup.sh script to check and verify that the script has not been invoked as root.

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"

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

• 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://localhost:8080