Challenge: Running dhis2 with jetty runner only

Support - Assistance technique
1

Hello,

I am trying to run dhis.war with jetty-runner.jar only.

I’ve tried tomcat and it works fine.
I’ve tried dhis-live-with-dependencies.jar but it does not work.
I don’t want to run it with maven mvn tomcat:run on the repo.

I think there should be a standalone method of running dhis really quick.

This is all I want to do:

java -jar jetty-runner.jar --path /dhis dhis.war

But when I run the command, I get a directory index of files in the dhis.war on localhost:8080/dhis

I’m using jdk17 on ubuntu
The dhis.conf is in the root folder.
Environment set export DHIS2_HOME=$PWD

Please assist.

Thanks.

2

Hi Pitsolu,

Running DHIS2 with jetty-runner is not supported and won’t work for a production setup. The only supported way to run DHIS2 without deploying it to a separate application server is to use the embedded Tomcat build, which has been available since 2.42. It is not documented yet, but it works.

From the dhis-2/ directory, build it with the embedded profile:

mvn clean package -pl dhis-web-server -am -DskipTests --activate-profiles embedded

Then run it:

export DHIS2_HOME=/path/to/your/dhis2-home
java -jar dhis-web-server/target/dhis.war

It listens on port 8080 by default. You can override this with the SERVER_PORT environment variable or the -Dserver.port=… system property. Make sure dhis.conf is placed inside $DHIS2_HOME.

Best regards,
Morten Svanæs

3

Hey Pitsolu!

The directory listing you’re seeing is a strong hint that Jetty isn’t initializing the servlet context from your WAR, it’s treating it like a static resource instead of deploying it. Here’s what’s most likely going wrong:

1. Your Jetty Runner version is probably incompatible

This is almost certainly the root cause. DHIS2 relies on the javax.* servlet namespace, and Jetty 10+ dropped that in favour of Jakarta. Grab the 9.4.x runner specifically:

bash

wget https://repo1.maven.org/maven2/org/eclipse/jetty/jetty-runner/9.4.53.v20231009/jetty-runner-9.4.53.v20231009.jar

2. Use absolute paths and pass DHIS2_HOME as a JVM system property

Relative paths can silently fail at startup. Do both the env var and the -D flag. It improves reliability considerably:

bash

export DHIS2_HOME=/absolute/path/to/your/conf/folder

ls $DHIS2_HOME/dhis.conf # make sure this exists before proceeding

3. Run it like this:

bash

java -Xmx2g -Xms1g \

-DDHIS2_HOME=$DHIS2_HOME \

-Djava.io.tmpdir=./tmp \

-jar jetty-runner-9.4.53.v20231009.jar \

–port 8080 \

–path /dhis \

dhis.war

The tmpdir flag is worth including. DHIS2 needs to write temp files and will silently misbehave if the default temp directory isn’t writable.

4. Sanity-check your WAR

Just to rule out a bad build:

bash

jar tf dhis.war | head -20

You should see WEB-INF/web.xml near the top. If you don’t, the WAR itself is the problem, not Jetty.

Heads Up: DHIS2 is deeply optimised for Tomcat, usingTomcat-specific JNDI pooling internally. Jetty Runner can work for quick local testing, but if you hit more weird behaviour down the line, that’s likely why. For anything beyond a quick dev spin, Tomcat 9 + PostgreSQL is where you’ll have the smoothest experience.