Installing DHIS2 on a Windows Server

Recently a college contacted me asking how they can install DHIS2 on a Windows server which they have just received on their premises. Since most tutorials available on the internet discuss installing DHIS2 on a server running a Linux distribution, he was finding it difficult to follow the steps outlined in those tutorials.

I decided to write this small tutorial for anyone interested in learning about installing DHIS2 on a Windows Server.

What is DHIS2?

For those who are unfamiliar, DHIS2 is a health information management system for collecting, analyzing, reporting and disseminating aggregated and individual-level health data.

DHIS2 is developed by the University of Oslo and released under the BSD license as free and open-source software backed up by a global community.

Hardware

The computer I installed DHIS2 was an Amazon Lightsail virtual machine running Windows Server 2019 with 2GB of ram and 60GB of hard drive space.

The steps

Download and install Java

The first step is to install Java.

DHIS2 requires Java 11 to run and it is important to download the correct JDK that matches your system requirements, my initial attempt failed when I mistakenly downloaded Java runtime environment (JRE) which was designed for 32-bit computers, however, the Windows server was a 64-bit computer.

I suggest downloading and installing the Microsoft Build of OpenJDK on your Windows server following the link below,

https://learn.microsoft.com/en-us/java/openjdk/download

Try to avoid downloading newer versions of JDKs as there is a risk you might run into errors because at the time of writing DHIS2 currently supports Java 11.

Download and install Postgres

DHIS2 requires PostgreSQL as the database management system, therefore you have to download and install PostgreSQL and install it on your computer.

You can download and install Postgres for Windows by following this link, I recommend downloading and installing PostgreSQL version 14 for DHIS2.

https://www.enterprisedb.com/downloads/postgres-postgresql-downloads

Download the setup and install PostgreSQL on your Windows server. After installing Postgres it is important to install the PostGIS extension which is required for DHIS2 to function.

You can install PostGIS by opening the “Stack Builder” application that you will find under Postgres in your start menu.

From the Stack Builder application, select the latest PostGIS version as the version to be installed, at the end of the wizard, Stack Builder will install PostGIS on your Windows server.

Setup Postgres user and Postgres Database

Creating a non-super-user postgres user for DHIS2

Access the PostgreSQL shell by opening the SQL Shell (psql) application from the start menu.

Create a user named dhis with the following command.

CREATE USER dhis;

After creating a user with the username dhis change the privileges of the user to match the privileges given in the DHIS2 installation documentation for Ubuntu.

ALTER USER dhis WITH NOCREATEDB NOCREATEROLE;

Next, change the password for the postgres user we created above. For this tutorial, the password I’m using is dhis2. However, I suggest using a strong password when implementing DHIS2 in a production environment.

ALTER USER dhis WITH PASSWORD 'dhis2';

Creating a database for DHIS2

The next step is creating the database that will store the data of your DHIS2 instance. To create the database run the following command on your PostgreSQL shell (PSQL).

For this tutorial I’m creating a database named dhis2.

CREATE DATABASE dhis2;

The database that you just created is still owned by the default postgres superuser postgres, the next step involves handing over the ownership of the database to the dhis user that we just created in the above step.

To transfer ownership of the database, execute the following command on the Postgres shell.

ALTER DATABASE dhis2 OWNER TO dhis;

Now that we have transferred the ownership of the database to the newly created user, we have to load the PostGIS extension on the newly created dhis2 database.

Before loading the PostGIS extension, first change the active database to the newly created dhis2 database.

\connect dhis2;

After switching the database, load the POSTGIS extension to the dhis2 database by running the following command in the psql shell,

CREATE EXTENSION postgis;

Create DHIS2 configuration file

Create a DHIS2 configuration file named dhis.conf in a folder named DHIS2_home\config inside the C: drive of the Windows Server.

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

# 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 = dhis2

# ----------------------------------------------------------------------
# Server
# ----------------------------------------------------------------------

# Enable secure settings if deployed on HTTPS, default 'off', can be 'on'
# server.https = on

# Server base URL
# server.base.url = https://server.com

Replace the connection.username with the username of the postgres user we created which is dhis, and replace connection.password with the password of the postgres user provided in the connection.username parameter.

Download and setup tomcat-9

For this tutorial, we are going to use Tomcat to host the DHIS2 instance, and you can download Tomcat through the Apache website,

https://tomcat.apache.org/

I suggest you use Tomcat 9 but I don’t think there will be an issue with using Tomcat 10 to run your DHIS2 instance.

Download the tomcat 9 instances and unzip the file to a preferred location. The next step involves changing the settings of the Tomcat 9 server to run DHIS2.

Changing the Tomcat 9 settings to run DHIS2

First, we have to point to the location of the DHIS2 configuration file, open the context.xml file within the Tomcat folder and add the following value within the context block of the XML file and set the path pointing to the location of the dhis.conf file that you created.

You only need to point to the root folder which contains the dhis.conf file, DHIS2 will automatically load the configurations when starting the Tomcat server

<Environment name="dhis2-home" value="/DHIS2_home/config" type="java.lang.String" override="true"/>

Next, open the server.xml file inside the unzipped Tomcat folder, and set relaxedQueryChars value in the Connector property. You can also specify the port which DHIS2 run. The default port for Apache Tomcat is 8080. However, you can always get rid of the port number using a reverse proxy with nginx.

<Connector port="8080" protocol="HTTP/1.1"
  connectionTimeout="20000"
  redirectPort="8443"
  relaxedQueryChars="[]" />

Finally, we have to set the environment variables on Tomcat, open the setenv.bat file inside the bin folder of your unzipped Tomcat folder, if there is no setenv.bat file, create a new setenv.bat file inside the bin folder with your favourite text editor.

JAVA_HOME	The path pointing to your java installation
JAVA_OPTS	The maximum and minimum memory allocated for your DHIS2 instance
DHIS2_HOME	The location of the DHIS2 configuration folder

You can set the environment variables in the setenv.bat file following the code snippet below.

set "JAVA_HOME=C:\Program Files\OpenJDK\jdk-11.0.18.10-hotspot"
set "JAVA_OPTS=-Xms500m -Xmx1000m"
set "DHIS2_HOME=C:\DHIS2_home\config"

Setting the DHIS2_HOME environment variable in the setenv.bat file is an alternative way to point to the location of the DHIS2 configuration file, which we have done by setting the DHIS2_HOME value in the context.xml file in one of the above steps.

The JAVA_OPTS sets the minimum and maximum memory (RAM) that can be allocated for the Tomcat server. There the -Xms means the minimum memory allocated while the -Xmx is the maximum amount of memory allocated. You will be setting the value in megabytes. In this example since our server is a 2GB windows server, I’ve set the minimum allocated memory as 500 megabytes, and the maximum allocated memory as 1000 megabytes.

The maximum allocated memory should be less than the system memory, and you will have to leave some memory for the operating system and other processes. Therefore it’s a good practice to leave 2-3 GB for the system processes depending on the amount of system memory that is available at your disposal.

Download DHIS2 war file

You can download the DHIS2 war file from the official DHIS2 website,

https://dhis2.org/downloads/

At the time of writing, the latest available version was 2.39 which I installed on the Windows server.

Copy the downloaded war file into the webapps folder of your Tomcat server.

Starting the Tomcat server

To start the Tomcat server, open PowerShell on your Windows server, change the directory to the tomcat server using the cd command and run the /bin/startup.bat file from PowerShell. Once the server has started, you will be able to access the DHIS2 installation by navigating to localhost:8080 from the browser in the Windows server.
./startup.bat

./startup.bat

Stopping the Tomcat server

Stopping the tomcat server is similar to starting the server, just run the /bin/shutdown.bat file in the tomcat folder from the PowerShell and it will shutdown the tomcat server.

./shutdown.bat

If there are any questions regarding installing DHIS2 on a Windows server, leave your questions as a comment.

---