Setting up DHIS2 core dev environment

I am new to the DHIS2 community, and am trying to set up a development environment so that I can (hopefully) contribute to the core project eventually.

I am following the steps on this page: Basic DHIS2 setup | DHIS2 Developer Portal

But, they are obviously out of date. I did install postgres 10.18, instead of 9.6. But, there was no mention of the requirement to install postgis prior to loading the data, for example. And the data file mentioned no longer exists.

I finally managed to get the sample data to load.

My question is… is there a better document to follow for setting up a dev environment for core? Am I going to run into other issues if I continue to work using the page listed above?

Thanks for any guidance.


I was able to follow the rest of the steps to successfully build and deploy the dhis.war file locally. I was then able to load the app in a browser and log in. So, it appears that the problematic section of the getting started document is the database section.

Also, are java 8 and tomcat 8 the correct versions to be using? I actually built and ran using java 11 without issue.

Even though the application seemed to load fine and I was able to log in, I noticed this exception in the catalina.out file

org.postgresql.util.PSQLException: ERROR: relation “analytics_event_vbqh0ynb2wv” does not exist

I had downloaded the sample database script from 2021-09-01 from here:

But, maybe I need to run an update script as well?

Welcome to the community @ddaley! :tada: Very pleased that you are sharing your experience, and I’m looking forward to your contributions and discussions too! :+1:

May I ask you how you got to that page because it does seem as you mentioned out of date and is not added anywhere in the pages (unless I happen to missed it); however, I would ask you to follow the tutorial which is linked from the homepage (Environment Setup | DHIS2 Developer Portal)

Additionally, for the requirements please see the info from the installation docs:

Software requirements

Later DHIS2 versions require the following software versions to operate.

  • An operating system for which a Java JDK or JRE version 8 or 11 exists. Linux is recommended.
  • Java JDK. OpenJDK is recommended.
    • For DHIS 2 version 2.35 version and later, JDK 11 is recommended and JDK 8 or later is required.
    • For DHIS 2 versions older than 2.35, JDK 8 is required.
  • PostgreSQL database version 9.6 or later. A later PostgreSQL version such as version 13 is recommended.
  • PostGIS database extension version 2.2 or later.
  • Tomcat servlet container version 8.5.50 or later, or other Servlet API 3.1 compliant servlet containers.
  • Cluster setup only (optional): Redis data store version 4 or later.

Have you seen the DHIS2 App development workshops? These are the playlists for the web app track which I hope you’ll find useful - there’s the android track too if you want to develop android apps!
Playlist for workshop 1:

Playlist for workshop 2:

I think it has to do with the Data Administration and maintenance and many more of these similar issues might appear!

Thanks! Please let me know what you end up with! (:

Thanks for the response!

May I ask you how you got to that page because it does seem as you mentioned out of date

I don’t remember exactly how I found that page. I believe it was a search on duck duck go about setting up a dev environment for DHIS2 core.

It appears that I managed to install the correct system requirements. I am running java 11 on Ubuntu and am running postgres 10.18 with PostGIS and Tomcat 8.x.

Have you seen the DHIS2 App development workshops?

I have watched some of the videos from the workshop. However, those videos seem to be focused on developing front end applications. As a long time java developer, I am more interested in contributing to the core project, which is written primarily in java. Eventually, I would like to look into developing apps as well.

1 Like

You’re welcome, and thank you! Please feel free to continue sharing your experiences like it’s your blog because I’m sure this will help the community. I wish you good luck! I want to learn the app development as well! I’m still on workshop 1 though and still have a lot to learn but it’s a lot of fun. (:

What is your dhis.conf file look like? Add this line to this file too
connection.schema = update if you dont have it.
It will update all SQL Schemas and create the one, which doesn’t exist during the launch time.
Also this error can be because of different version of schema table and the version of dhis2-core, which you have installed. If you’ve downloaded the latest code from github, then it’s version 2.38. I dont know the database which you’ve restored is for this dhis2-core version or no.

Anyway you did a great job by getting so far using the docs. I dont really think the docs are much of a use, there are always something which the docs dont say and you have to debug and figure it out yourself out of my experience with this platform so far…

Also the last recommendation would be to create an empty database and point the dhis.conf to that file. That way you definitely shouldn’t have any errors.


Thank you. I checked my dhis.conf file, and I do have that line. I pulled the database script from here:

However, I only now noticed that they are not listed in order chronologically, and I had taken the first one (dated 2021-09-01). I dropped the database and used the script [sierra-leone/2.37/dhis2-db-sierra-leone.sql.gz], which is newer, but am still seeing those same errors.

Is there a better database script to use? Or, are you suggesting to create a blank database and set connection.schema = create? I would like to have test data though.

Thanks again,


UPDATE. I recreated an empty database using the script from github


And, the application starts without error… and without any data. I was able to install an App using the App Manager. However, I notice this error (and similar errors from other pages). I am using Firefox 932.0 on Ubuntu 20.04.3. Not sure if that is relevant. I am not sure if this error is actually affecting the application though.

java.lang.IllegalArgumentException: Invalid character found in the request target [/dhis/api/me.json?fields=organisationUnits[id,displayName,programs[id],level,path,children[id,displayName,programs[id],level,children[id]]],teiSearchOrganisationUnits[id,displayName,programs[id],level,path,children[id,displayName,programs[id],level,children[id]]]&paging=false ]. The valid characters are defined in RFC 7230 and RFC 3986

Well, my main goal for now was to be able to make calls to the REST API. I found that I can run dhis-web-embedded-jetty.jar which provides access to the API. I am able to make calls to that successfully, without any errors. So, for now, I am up and running. I will continue to investigate the errors that I see when running dhis.war in tomcat when I have more time.

Thanks for the help.


You dont have to compile the whole project and run it via Tomcat. You can actually debug any web module with jetty from either Eclipse or Intellij, I dont know what is your IDEA. If you want to debug the whole Project then you should debug web-portal with jetty.

Also you dont have to manually recreate the database using some schemas. As DHIS2 uses hibernate all the database schemas will be created automatically and for the dhis.conf its recommended to keep the schemas to connection.schema = update.

About the data I believe you can use DHIS2 import/export feature just for the migration of the data so you will not have database schema errors.

Good luck with your journey.

1 Like