D2 cluster changes: feedback needed on files added to DHIS2_HOME

Hi :smile:

We recently made some changes to how we build the DHIS2 Docker images. Some of the reasons are multi-arch support for the new Mac M1 chips :tada: and a more streamlined process for building images, among others.

However, these changes are affecting the d2 cluster tool. In the following text, we will distinguish between the images before and after the changes as “old” (before) and “new” (after; affecting Docker builds and releases starting from 2.39.0, 2.38.2, 2.37.9).

We bind mount the whole DHIS2_HOME directory from your host into the container. Meaning a directory on your machine like ./conf/DHIS2_home is mounted into the container at /DHIS2_home.

This allowed you to

  1. Add other configuration files besides dhis.conf, like a credentials file for Google Earth Engine.

  2. See the logs from DHIS2_HOME/logs directly on your machine, instead of via d2 cluster logs (docker logs) or within the container.

Using a bind mount for the whole DHIS2_HOME directory no longer works with the new images, as they are not running as root user anymore. Bind mounting changes ownership of DHIS2_HOME which makes it unwritable by DHIS2. (You can find more information about this here and here).

We are currently looking at possible fixes for the ownership issue and making d2 cluster compatible with both old and new images. In order to find the best solution we need to know:

  • What files besides dhis.conf or the google earth credentials do you put into your DHIS2_HOME?
  • What is your current workflow to get these files into the DHIS2_HOME?
1 Like

Hi @ivo,

Thanks for your post.

Let me answer your questions below in a little bit more detail:

DHIS2_HOME is a directory that contains various configuration files, log files, and other resources that are used by DHIS2. Some of the files that you may find in DHIS2_HOME include:

  1. dhis.conf: This file contains the configuration settings for DHIS2, such as the database connection settings and the URL of the DHIS2 instance.
  2. log4j.properties: This file contains the configuration settings for the DHIS2 logging system.
  3. webapps/: This directory contains the web applications that are deployed to the DHIS2 instance.
  4. deployments/: This directory contains the deployed DHIS2 web applications.
  5. security/: This directory contains security-related files, such as SSL certificates and keystores.
  6. lib/: This directory contains the libraries and other dependencies that are used by DHIS2.
  7. tmp/: This directory contains temporary files that are used by DHIS2.
  8. google earth credentials: If you are using Google Earth integration with DHIS2, you may need to include credentials for accessing the Google Earth API in this directory.

It’s important to note that the specific files and directories that you will find in DHIS2_HOME will depend on the version of DHIS2 that you are using, as well as any additional modules or features that you have installed.

There are several ways to get files into DHIS2_HOME, depending on the specific needs of your case and the resources available to you. Here are some possible approaches you could consider:

  1. Copy the files manually: You can simply copy the necessary files into DHIS2_HOME using a file manager or the command line. This method is simple, but it can be time-consuming if you have a large number of files to transfer.
  2. Use a script: If you have a large number of files to transfer, you can use a script to automate the process. For example, you could use a bash script on a Linux system to copy the files from a source directory to DHIS2_HOME.
  3. Use a configuration management tool: If you have a complex environment with multiple servers and a large number of files to manage, you may want to consider using a configuration management tool such as Ansible or puppet. These tools allow you to automate the deployment and management of your DHIS2 system, including the transfer of files to DHIS2_HOME.
  4. Use an application deployment tool: If you are deploying DHIS2 as part of a larger application, you may want to use an application deployment tool such as Jenkins or GitLab CI to automate the process of transferring files to DHIS2_HOME. These tools can help you automate the entire deployment process, including building, testing, and deploying your application.

Ultimately, the best approach will depend on your specific needs and the resources available to you.

Last but not least It may be helpful to consult with a DHIS2 administrator expert, or seek guidance from the DHIS2 documentation if you are unsure which approach is best for your case.

Best regards,

1 Like

Thanks a lot for your detailed answer @ayman.tuffaha :smile:

My question was geared towards peoples workflows using d2. So what is it that you specifically do during development. This could help us understand what changes we can make to improve d2 or at least not reduce your efficiency.


Thanks @ivo,

Oh I see :sweat_smile:

Best regards,

1 Like