Up to Date Install Guide for DHIS2
Problem
- The installation guide for DHIS2 is woefully out of date and won’t work as described
- They recommend using Ubuntu Server 18.04, which has reached EOL and even if you follow their recommendation you cannot get a install of PostgreSQL 12 without pulling it from the archive repo via a complicated workaround
- This guide was written while installing DHIS2 on a test machine completely devoid of test data for a proof of concept, so it is probably not what you want to do in a production environment
- Here is a better PROD guide using lxc containers in Ubuntu: https://github.com/bobjolliffe/dhis2-tools-ng
- And here is one using Docker containers: https://github.com/baosystems/docker-dhis2
- Although the devs themselves do not recommend Docker in production ¯\_(ツ)_/¯
- If you are interested in just testing DHIS2 with data in DB already there is this guide from the devs using Docker containers also: https://developers.dhis2.org/docs/guides/spin-up-local-instance/
Solution (AKA the guide)
Note: I will be jumping back and forth between this guide and the official documentation but I will try to keep the links correct when referencing the official docs
- Install Ubuntu Server 22.04.4 Jammy Jellyfish
- I am going to assume you know how install a linux server distro (Download the ISO, use Rufus to create a bootable USB, take the default drive partitions suggested by the installer, enable SSH for use with PuTTY to allow remote admining, pick en-us as you locale for compatibility purposes, blah, blah, blah)
- You will want to do all the below configuration in PuTTY as there is a lot of copying and pasting below that can really speed up the process of configuring DHIS
- During the install you will be prompted to create a root or admin user. Do not name this user “dhis.” pick something along the lines of “dhisadmin” or “admin-dhis,” as you will be creating a separate dhis user shortly
- The “dhisadmin” user is you, has root access and is the user that will be logging into or SSHing into the Ubuntu Server, whereas “dhis” will be used to start and stop tomcat which runs the DHIS2 software
- Of course be sure to record this password in a secure password manager
- Once you have the server up and running follow these portions of the official docs:
- https://docs.dhis2.org/en/manage/performing-system-administration/dhis-core-version-master/installation.html#install_creating_user
- Be sure to record this username and password in your password vault
- https://docs.dhis2.org/en/manage/performing-system-administration/dhis-core-version-master/installation.html#install_creating_config_directory
- The docs unfortunately skip a step here and no DHIS environment variable is ever created if you follow them word for word; so we will run:
sudo nano /etc/environment
#and add the following line to the environment file and save with CTRL+O and exit with CTRL+X
DHIS2_HOME=”/home/dhis/config”
- https://docs.dhis2.org/en/manage/performing-system-administration/dhis-core-version-master/installation.html#install_setting_server_tz
- But here you can ignore the locale stuff if you are sticking with “en-us” as I would advise
- Now we are ready to install PostgreSQL as per the docs:
- https://docs.dhis2.org/en/manage/performing-system-administration/dhis-core-version-master/installation.html#install_postgresql_installation
- But the docs are scuffed here as well so use the commands below to install PostgreSQL 14 and PostGIS for mapping purposes (as of the time of writing version 14 is the default version installed from the Ubuntu repos):
sudo apt-get install postgresql
sudo apt-get install postgresql-14-postgis-3
sudo apt-get install postgis
- Following the docs again, you will create a “dhis” user for the PostgreSQL server and a DB with the name dhis2
- Creating this DB admin user “dhis” will result in another username and password, which you will need to record in your password vault and which is used when connecting to DB via PGadmin (is similar to SQL Server Management Studio) or Power BI or some such. Keep this password handy you will need in the “DHIS configuration” section below
- As an aside here, I followed the DHIS2 dev’s advice when connecting to the PostgreSQL server / DB and did not go and open any ports on the server or the DB service; I just use an SSH PuTTY tunnel to allow access to via localhost (AKA you connect to your Ubuntu Server via PuTTY / port 22 and then create a connection to port 5432, the default PostgreSQL port, and can connect directly to the PostgreSQL DB from Power BI or PGadmin). Here is a more detailed guide on this PuTTY trick.
- Continue following the docs and enable the postGIS features in PostgreSQL. I also created the other two extensions that they mentioned even though it might be redudant. Move on to the “PostgreSQL performance tuning” section
- https://docs.dhis2.org/en/manage/performing-system-administration/dhis-core-version-master/installation.html#install_postgresql_performance_tuning
- Here we have a little problem; we didn’t install version 12 of PostgreSQL, but instead version 14 so we have to change the directory of the .conf file that we are going to edit:
#So run this command instead
sudo nano /etc/postgresql/14/main/postgresql.conf
- Now we have to edit a bunch of lines in this big .conf file. The line they want us to edit are all over the place as well, so use CTRL+W to search in nano and find the write lines to change, following the docs’ recommendations and then restart the PostgreSQL service as they recommend
- Install Java by following the docs:
- Continuing with the docs, we come to the “DHIS2 configuration” section
- https://docs.dhis2.org/en/manage/performing-system-administration/dhis-core-version-master/installation.html#install_database_configuration
- Here you will need to create the .conf file as stated and substitute your DB admin user’s (dhis) password, which you created after installing PostgreSQL:
#For the line:
connection.password = xxxx
#Remove the xxxx’s and type the DB admin password in plaintext
- They then go on a bit of tangent about using another environment variable to store the DB admin password as an environment variable instead of typing it in plaintext here. I think there are pros and cons to both approaches. I’ll leave this one up to you.
- Finish this section by changing the rights to the .conf file as recommended
- Continue into the “Tomcat and DHIS installation” section
- https://docs.dhis2.org/en/manage/performing-system-administration/dhis-core-version-master/installation.html#install_tomcat_dhis2_installation
- Here we need to make some changes, so I am just going to give you the updated commands to install Tomcat 9 instead of 8 and they also leave out some nano commands, when they want you edit some more configuration files, but I will include them:
#Install Tomcat9
sudo apt-get install -y tomcat9-user
#Create an instance in the dhis user’s directory
sudo tomcat9-instance-create /home/dhis/tomcat-dhis
#Give the dhis user ownership of these files and folders recursively
sudo chown -R dhis:dhis /home/dhis/tomcat-dhis/
#Edit the setenv.sh file
sudo nano /home/dhis/tomcat-dhis/bin/setenv.sh
#Add these lines to the setenv.sh file using nano (note the docs use java version 11 but we installed openJDK 17) then save and exitJAVA_HOME='/usr/lib/jvm/java-17-openjdk-amd64/'JAVA_OPTS='-Xms4000m -Xmx7000m'DHIS2_HOME='/home/dhis/config'
#Edit the server.xml file using nano
sudo nano /home/dhis/tomcat-dhis/conf/server.xml
#Find the block that starts with <Connector and adjust to look like the block below then save and exit<Connector port="8080" protocol="HTTP/1.1"connectionTimeout="20000"redirectPort="8443"relaxedQueryChars="[]" />
- Now you are ready to download the DHIS2 software itself, and I will provide a curl command unlike the docs to make it easy on you
- Note: at the time of this writing the latest version of DHIS2 was 41, this will surely change soon so visit https://releases.dhis2.org/ to check on the current stable version and adjust the curl command below accordingly
#This will download version 41 and put it in the correct folder while renaming the file to ROOT.war
curl -o /home/dhis/tomcat-dhis/webapps/ROOT.war https://releases.dhis2.org/41/dhis2-stable-41.0.0.war
- With the above curl command you can ignore the mv command from the docs, but we do want to edit the startup.sh script as recommended so run:
sudo nano /home/dhis/tomcat-dhis/bin/startup.sh
#And copy and paste the code block from the docs into this file
- The “Running DHIS2” section is all correct and you can now start and stop the software with the startup.sh and shutdown.sh commands
- You can also use ifconfig to get your Ubuntu server’s IP address, so that you can access DHIS2 from a browser, for instance if ifconfig tells you that Ubuntu server is on 10.1.1.10 your DHIS2 instance can be accessed at http://10.1.1.10:8080
- We will change this port and look at installing nginx and https plus some security changes in my next blog post. Thanks for reading!