Running DHIS2 on Ubuntu 24.04 with Tomcat 10

Server Administration - Administration-du-Serveur
,
1

Running DHIS2 on Ubuntu 24.04 with Tomcat 10

As you know, Ubuntu 24.04, the latest Long-Term Support (LTS) release, was launched in April 2024. It’s generally recommended to deploy new DHIS2 instances on the most recent LTS releases to benefit from the latest security updates and fixes.

While Ubuntu 24.04 offers updated software versions, including PostgreSQL 16 and Tomcat 10, Tomcat 10’s significant namespace changes (from javax to jakartaee) currently pose compatibility issues with DHIS2. This means you cannot directly run DHIS2 on Tomcat 10 without modifications.

To run DHIS2 on Ubuntu 24.04, you have these options:

  1. Manual Tomcat 9 Installation: You can manually download and install Tomcat 9 from the official Tomcat release website. However, this requires additional setup, including creating a user to run Tomcat and configuring systemd control scripts. You’ll also need to manage updates and patches yourself, which can be time-consuming.
  2. Using Tomcat 10 with a Migration Script: We recommend this approach. Our DHIS2-server-tools automate the process, detecting the operating system version and installing the appropriate Tomcat version (Tomcat 9 for Ubuntu 22.04/20.04, Tomcat 10 for Ubuntu 24.04). The tools also apply necessary adjustments to make DHIS2 libraries compatible with Tomcat 10.

To use Tomcat 10 on Ubuntu 24.04:

  1. Install Tomcat 10 and the migration tool:
    apt install tomcat10 tomcat-jakartaee-migration

  2. Download the DHIS2 WAR file and convert it: Here we assume you’ve downloaded the war file and is named dhis2.war, run conversion as below.
    javax2jakarta dhis.war dhis-jakarta.war

The converted WAR file should run smoothly on Tomcat 10.

Why choose Tomcat 10 with migration tool?

  • Security: Its challenging updating and upgrading manually installed Tomcat 9 package. You want apt package manager automating upgrades, and on ubuntu 24.04 its tomcat 10.

While the conversion step adds a bit of complexity, it’s a more secure and efficient way to run DHIS2 on Ubuntu 24.04. Its an extra step but it’s already automated and integrated into our ansible install tools, refer to the Ansible playbook at line 72 here

We’re currently discussing ways to simplify the process of running DHIS2 on Ubuntu 24.04. One possibility is to provide separate WAR files for Tomcat 9 and Tomcat 10. However, as you’ve seen, manually converting the WAR file for Tomcat 10 isn’t overly complex. If you choose to go this route, please share your experiences and any challenges you encounter. Your feedback will help us improve the process for future users.

7 Likes