🚀 DHIS2 Installation on DigitalOcean (Ubuntu 22.04)

This guide walks you through a full DHIS2 installation on Ubuntu 22.04 using DigitalOcean, including server setup, PostgreSQL/PostGIS, Tomcat, DHIS2 deployment, cleanup, and troubleshooting HTTP 404 errors.

Server Requirements

• DHIS2 Version: 2.40
• Tomcat: 9
• Postgres: 14.18
• Java: OpenJDK 17
• Server Specs: Ubuntu 22.04 LTS, 4 GB RAM recommended (2 GB minimum), 2 vCPU
• Domain: yourdomain.com

Phase 1: Server Configuration

Step 1: Install Nginx

sudo apt update
sudo apt install nginx -y
sudo systemctl enable nginx
sudo systemctl start nginx
sudo systemctl status nginx

Test locally:

curl http://localhost

You should see the default Nginx page.

Step 2: Configure Nginx for DHIS2

sudo nano /etc/nginx/sites-available/yourdomain.com

Paste:

server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

sudo ln -s /etc/nginx/sites-available/yourdomain.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Step 3: Configure DNS

Log in to DigitalOcean → Networking → Domains → yourdomain.com. Add an A record:

Test propagation:

dig yourdomain.com
nslookup yourdomain.com

Step 4: (Optional) Enable SSL via Let’s Encrypt

sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d yourdomain.com

Access your site:

• http://yourdomain.com
or
• https://yourdomain.com

Phase 2: DHIS2 Installation

Step 1: Basic Server Setup

sudo apt update && sudo apt upgrade -y
sudo dpkg-reconfigure tzdata   # set timezone
sudo mkdir -p /var/www/yourdomain.com/config
sudo useradd dhis -s /bin/false
sudo passwd dhis  # enter password, e.g., 987654321 (Strong password recommended)

Step 2: Install PostgreSQL + PostGIS

sudo apt install postgresql postgresql-contrib postgis -y
sudo systemctl enable postgresql
sudo systemctl start postgresql

sudo -u postgres createuser -SDRP dhis  # enter password, e.g., 987654321 (Strong password recommended)
sudo -u postgres createdb -O dhis dhis2
sudo -u postgres psql -d dhis2 -c "CREATE EXTENSION postgis;"

Step 3: DHIS2 Config File

sudo nano /var/www/yourdomain.com/config/dhis.conf

Paste:

# 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://localhost:5432/dhis2

# Database username
connection.username = dhis

# Database password
connection.password = 987654321

# Encryption password (set a strong password)
encryption.password = xxxx

Step 4: Install Java

sudo apt install openjdk-17-jdk -y
java -version

Step 5: Install Tomcat 9 and Create Instance

sudo apt update
sudo apt install tomcat9 tomcat9-admin tomcat9-user -y
sudo tomcat9-instance-create /var/www/yourdomain.com/tomcat-dhis
sudo chown -R dhis:dhis /var/www/yourdomain.com/tomcat-dhis

Step 5a: Set Environment Variables

sudo nano /var/www/yourdomain.com/tomcat-dhis/bin/setenv.sh

Paste:

#!/bin/sh
CATALINA_HOME=/usr/share/tomcat9
export JAVA_HOME='/usr/lib/jvm/java-11-openjdk-amd64/'
export JAVA_OPTS='-Xmx2500m -Xms1500m -XX:+UseG1GC'
export DHIS2_HOME='/var/www/yourdomain.com/config'

sudo chmod +x /var/www/yourdomain.com/tomcat-dhis/bin/setenv.sh

Step 6: Download and Deploy DHIS2 WAR

cd ~
wget https://releases.dhis2.org/2.40/dhis.war
sudo mv dhis.war /var/www/yourdomain.com/tomcat-dhis/webapps/ROOT.war
sudo chown dhis:dhis /var/www/yourdomain.com/tomcat-dhis/webapps/ROOT.war

Step 7: Start DHIS2

sudo -u dhis /var/www/yourdomain.com/tomcat-dhis/bin/startup.sh
tail -f /var/www/yourdomain.com/tomcat-dhis/logs/catalina.out

Access DHIS2 at:

• https://yourdomain.com
• Username: admin
• Password: district

Step 8: (Optional) Reverse Proxy + SSL with Nginx

sudo apt install nginx -y
sudo nano /etc/nginx/sites-available/yourdomain.com

Paste:

server {
    server_name yourdomain.com;
    location / {
        proxy_pass http://127.0.0.1:8080/;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

sudo ln -s /etc/nginx/sites-available/yourdomain.com /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx
sudo apt install certbot python3-certbot-nginx -y
sudo certbot --nginx -d yourdomain.com

Phase 3: Cleanup (Optional)

sudo systemctl stop tomcat9
sudo systemctl stop postgresql
sudo systemctl stop nginx
sudo apt purge -y tomcat9 tomcat9-admin tomcat9-user
sudo rm -rf /var/www/yourdomain.com/tomcat-dhis /var/lib/tomcat9 /etc/tomcat9
sudo apt purge -y postgresql postgresql-contrib postgis
sudo rm -rf /var/lib/postgresql /etc/postgresql /etc/postgresql-common /var/www/yourdomain.com/config
sudo apt purge -y nginx nginx-common nginx-core
sudo rm -rf /etc/nginx/sites-available/yourdomain.com /etc/nginx/sites-enabled/yourdomain.com
sudo apt autoremove -y
sudo apt autoclean -y

Phase 4: HTTP Status 404 – Not Found Fix

1️⃣ Stop Tomcat
/var/www/yourdomain.com/tomcat-dhis/bin/shutdown.sh

2️⃣ Remove old deployment
rm -rf /var/www/yourdomain.com/tomcat-dhis/webapps/ROOT
rm -f /var/www/yourdomain.com/tomcat-dhis/webapps/ROOT.war

3️⃣ Download fresh WAR
cd ~
wget https://releases.dhis2.org/2.40/dhis.war

4️⃣ Move to Tomcat webapps
sudo mv dhis.war /var/www/yourdomain.com/tomcat-dhis/webapps/ROOT.war
sudo chown dhis:dhis /var/www/yourdomain.com/tomcat-dhis/webapps/ROOT.war
sudo chmod 644 /var/www/yourdomain.com/tomcat-dhis/webapps/ROOT.war

5️⃣ Start Tomcat
/var/www/yourdomain.com/tomcat-dhis/bin/startup.sh

6️⃣ Monitor logs
tail -f /var/www/yourdomain.com/tomcat-dhis/logs/catalina.out

7️⃣ Verify deployment
Check that /var/www/yourdomain.com/tomcat-dhis/webapps/ROOT/WEB-INF exists.
Check database:
sudo -u postgres psql -l
sudo -u postgres psql -d dhis2
\dt   # list tables
\dx   # check extensions (PostGIS)