How make 2 DHIS2 instances on a Single Server

How make 2 DHIS2 instances on a Single Server


Hi @daniel1
You can follow the installation instructions here:

When you get to the section “Creating a user for DHIS2” and “Creating the configuration directory”, repeat those steps for each DHIS2 instance you want to run on the machine - in other words, create a user for each DHIS2 instance.
Similarly, for the DHIS2 configuration section, make sure you create a different configuration for each instance - one in each home directory for the user you created above.

For the Tomcat and DHIS2 installation, run the first step (sudo apt-get install tomcat8-user), then for the next steps, follow those for each dhis2 instance user you created above.

Lastly, you can start your DHIS2 instances individually like this:

sudo -u [dhisuser1] /home/[dhis2user1]/tomcat-dhis/bin/
sudo -u [dhisuser2] /home/[dhis2user2]/tomcat-dhis/bin/
sudo -u [dhisuser3] /home/[dhis2user3]/tomcat-dhis/bin/

Replace [dhis2userx] with your individual user accounts you created.

To automatically start them at reboot, add an entry to the crontab for each user to run the command above on reboot:

sudo su - [dhisuser1]
crontab -e

Add this to the cron file and save it:

@reboot ~/tomcat-dhis/bin/

Repeat these commands for each user / instance of DHIS2
It’s important to note that you must start each instance as the user account that the instance was created under - if you take shortcuts and run tomcat as sudo, the ownership of various files will be adjusted to the root user which will create problems when running it as the correct user. If you accidentally do this, just set ownership for the home directory and it’s contents with sudo chown -R [dhis2user1]:[dhis2user1] /home/[dhis2user1]
Replace [dhis2user1] with the user name

Let me know if any of this doesn’t make sense?


Thank you @Edward_Robinson for the support! :wave:

@daniel1 would you like to update us if you found the answer please? Feel free to post if you have more questions. Thank you!

1 Like

Hello @Edward_Robinson ,
Thank you for your post.
I followed the same steps mentioned in your post to run two instances on one server. But unfortunately not work.
When I run the first instance on port 8080, appear this picture:

and the same problem appears when I run the second instance on port 8081.
I am sharing with you Catalina’s file if you can help me:
<6>CATALINA_BASE: /home/dhis/tomcat-dhis
<6>CATALINA_HOME: /usr/share/tomcat9
<6>Command line argument: --add-opens=java.base/java.lang=ALL-UNNAMED
<6>Command line argument: --add-opens=java.base/
<6>Command line argument: --add-opens=java.rmi/sun.rmi.transport=ALL-UNNAMED
<6>Command line argument: -Djava.util.logging.config.file=/home/dhis/tomcat-dhis/conf/
<6>Command line argument: -Djava.util.logging.manager=org.apache.juli.ClassLoaderLogManager
<6>Command line argument: -Xms900m
<6>Command line argument: -Xmx1800m
<6>Command line argument: -Djdk.tls.ephemeralDHKeySize=2048
<6>Command line argument: -Djava.protocol.handler.pkgs=org.apache.catalina.webresources
<6>Command line argument:
<6>Command line argument: -Dignore.endorsed.dirs=
<6>Command line argument: -Dcatalina.base=/home/dhis/tomcat-dhis
<6>Command line argument: -Dcatalina.home=/usr/share/tomcat9
<6>Command line argument:
<6>The APR based Apache Tomcat Native library which allows optimal performance in production environments was not found on the java.library.path: [/usr/java/packages/lib:/usr/lib/x86_64-linux-gnu/jni:/lib/x86_64-linux-gnu:/usr/lib/x86_64-linux-gnu:/usr/lib/jni:/lib:/usr/lib]
<6>Initializing ProtocolHandler [“http-nio-8080”]
<6>Server initialization in [1,715] milliseconds
<6>Starting service [Catalina]
<6>Starting Servlet engine: [Apache Tomcat/9.0.31 (Ubuntu)]
<6>Deploying web application archive [/home/dhis/tomcat-dhis/webapps/ROOT.war]
<6>At least one JAR was scanned for TLDs yet contained no TLDs. Enable debug logging for this logger for a complete list of JARs that were scanned but no TLDs were found in them. Skipping unneeded JARs during scanning can improve startup time and JSP compilation time.

  • INFO 2023-02-05T18:00:11,223 Context variable dhis2-home not set ( [main])
  • INFO 2023-02-05T18:00:11,246 System property dhis2.home not set ( [main])
  • INFO 2023-02-05T18:00:11,247 Environment variable DHIS2_HOME not set ( [main])
  • INFO 2023-02-05T18:00:11,249 Directory /opt/dhis2 cannot be created ( [main])
  • ERROR 2023-02-05T18:00:11,255 No Home directory set, and /opt/dhis2 is not a directory ( [main])
    <2>Error deploying web application archive [/home/dhis/tomcat-dhis/webapps/ROOT.war]
    <2>java.lang.IllegalStateException: Error starting child
    <2> at org.apache.catalina.core.ContainerBase.addChildInternal(
    <2> at org.apache.catalina.core.ContainerBase.addChild(
    <2> at org.apache.catalina.core.StandardHost.addChild(
    <2> at org.apache.catalina.startup.HostConfig.deployWAR(
    <2> at org.apache.catalina.startup.HostConfig$
    <2> at java.base/java.util.concurrent.Executors$
    <2> at java.base/
    <2> at org.apache.tomcat.util.threads.InlineExecutorService.execute(
    <2> at java.base/java.util.concurrent.AbstractExecutorService.submit(
    <2> at org.apache.catalina.startup.HostConfig.deployWARs(
    <2> at org.apache.catalina.startup.HostConfig.deployApps(
    <2> at org.apache.catalina.startup.HostConfig.start(
    <2> at org.apache.catalina.startup.HostConfig.lifecycleEvent(
    <2> at org.apache.catalina.util.LifecycleBase.fireLifecycleEvent(
    <2> at org.apache.catalina.util.LifecycleBase.setStateInternal(
    <2> at org.apache.catalina.util.LifecycleBase.setState(
    <2> at org.apache.catalina.core.ContainerBase.startInternal(
    <2> at org.apache.catalina.core.StandardHost.startInternal(
    <2> at org.apache.catalina.util.LifecycleBase.start(
    <2> at org.apache.catalina.core.ContainerBase$
    <2> at org.apache.catalina.core.ContainerBase$
    <2> at java.base/
    <2> at org.apache.tomcat.util.threads.InlineExecutorService.execute(
    <2> at java.base/java.util.concurrent.AbstractExecutorService.submit(
    <2> at org.apache.catalina.core.ContainerBase.startInternal(
    <2> at org.apache.catalina.core.StandardEngine.startInternal(
    <2> at org.apache.catalina.util.LifecycleBase.start(
    <2> at org.apache.catalina.core.StandardService.startInternal(
    <2> at org.apache.catalina.util.LifecycleBase.start(
    <2> at org.apache.catalina.core.StandardServer.startInternal(
    <2> at org.apache.catalina.util.LifecycleBase.start(
    <2> at org.apache.catalina.startup.Catalina.start(
    <2> at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke0(Native Method)
    <2> at java.base/jdk.internal.reflect.NativeMethodAccessorImpl.invoke(
    <2> at java.base/jdk.internal.reflect.DelegatingMethodAccessorImpl.invoke(
    <2> at java.base/java.lang.reflect.Method.invoke(
    <2> at org.apache.catalina.startup.Bootstrap.start(
    <2> at org.apache.catalina.startup.Bootstrap.main(
    <2>Caused by: org.apache.catalina.LifecycleException: Failed to start component [StandardEngine[Catalina].StandardHost[localhost].StandardContext[]]
    <2> at org.apache.catalina.util.LifecycleBase.handleSubClassException(
    <2> at org.apache.catalina.util.LifecycleBase.start(
    <2> at org.apache.catalina.core.ContainerBase.addChildInternal(
    <2> … 37 more
    <2>Caused by: java.lang.IllegalStateException: Properties could not be loaded
    <2> at org.hisp.dhis.external.conf.DefaultDhisConfigurationProvider.loadDhisConf(
    <2> at org.hisp.dhis.external.conf.DefaultDhisConfigurationProvider.init(
    <2> at org.hisp.dhis.webapi.servlet.DhisWebApiWebAppInitializer.getConfig(
    <2> at org.hisp.dhis.webapi.servlet.DhisWebApiWebAppInitializer.onStartup(
    <2> at org.springframework.web.SpringServletContainerInitializer.onStartup(
    <2> at org.apache.catalina.core.StandardContext.startInternal(
    <2> at org.apache.catalina.util.LifecycleBase.start(
    <2> … 38 more
    <2>Caused by: org.hisp.dhis.external.location.LocationManagerException: External directory not set
    <2> at org.hisp.dhis.external.location.DefaultLocationManager.buildDirectory(
    <2> at org.hisp.dhis.external.location.DefaultLocationManager.getFileForReading(
    <2> at org.hisp.dhis.external.location.DefaultLocationManager.getInputStream(
    <2> at org.hisp.dhis.external.location.DefaultLocationManager.getInputStream(
    <2> at org.hisp.dhis.external.conf.DefaultDhisConfigurationProvider.loadDhisConf(
    <2> … 44 more
    <6>Deployment of web application archive [/home/dhis/tomcat-dhis/webapps/ROOT.war] has finished in [21,754] ms
    <6>Starting ProtocolHandler [“http-nio-8080”]
    <6>Server startup in [22,059] milliseconds
    <6>Pausing ProtocolHandler [“http-nio-8080”]
    <6>Stopping service [Catalina]
    <6>Stopping ProtocolHandler [“http-nio-8080”]
    <6>Destroying ProtocolHandler [“http-nio-8080”]
    <4>Failed to clear soft references from ObjectStreamClass$Caches for web application [ROOT]
    <4>java.lang.ClassCastException: class$Caches$1 cannot be cast to class java.util.Map ($Caches$1 and java.util.Map are in module java.base of loader ‘bootstrap’)
    <4> at org.apache.catalina.loader.WebappClassLoaderBase.clearCache(
    <4> at org.apache.catalina.loader.WebappClassLoaderBase.clearReferencesObjectStreamClassCaches(
    <4> at org.apache.catalina.loader.WebappClassLoaderBase.clearReferences(
    <4> at org.apache.catalina.loader.WebappClassLoaderBase.stop(
    <4> at org.apache.catalina.loader.WebappLoader.stopInternal(
    <4> at org.apache.catalina.util.LifecycleBase.stop(
    <4> at org.apache.catalina.core.StandardContext.stopInternal(
    <4> at org.apache.catalina.util.LifecycleBase.stop(
    <4> at org.apache.catalina.util.LifecycleBase.destroy(
    <4> at org.apache.catalina.core.ContainerBase.removeChild(
    <4> at org.apache.catalina.core.ContainerBase.destroyInternal(
    <4> at org.apache.catalina.util.LifecycleBase.destroy(
    <4> at org.apache.catalina.core.ContainerBase.removeChild(
    <4> at org.apache.catalina.core.ContainerBase.destroyInternal(
    <4> at org.apache.catalina.util.LifecycleBase.destroy(
    <4> at org.apache.catalina.core.StandardService.destroyInternal(
    <4> at org.apache.catalina.util.LifecycleBase.destroy(
    <4> at org.apache.catalina.core.StandardServer.destroyInternal(
    <4> at org.apache.catalina.util.LifecycleBase.destroy(
    <4> at org.apache.catalina.startup.Catalina.stop(
    <4> at org.apache.catalina.startup.Catalina$

Hello @jamal_aljadan

Your Tomcat seems to be properly installed, also, it detects the DHIS2 app (named ROOT.war and located in /home/dhis/tomcat-dhis/webapps/ROOT.war). But as you can see from the quote above, it seems that you have not properly configured (or you are not providing well) the DHIS2 config.

If you follow the guide: System Administration Guide - DHIS2 Documentation you will see that you need to the define the configuration directory (actually it is what is called DHIS2_HOME and config file is expected there). You can define this either via a Tomcat directive (not very common) or via an environment path. The later seems more common and you can find it in the guide where the is explained.

Next edit the file tomcat-dhis/bin/ and add the lines below.

  • JAVA_HOME sets the location of the JDK installation.
  • JAVA_OPTS passes parameters to the JVM.
    • -Xms sets the initial allocation of memory to the Java heap memory space.
    • -Xmx sets the maximum allocation of memory to the Java heap memory space. This should reflect how much memory you would like to allocate to the DHIS 2 software application on your server.
  • DHIS2_HOME sets the location of the dhis.conf configuration file for DHIS 2.

Check that the path the Java binaries are correct as they might vary from system to system, e.g. on AMD systems you might see /java-11-openjdk-amd64. Note that you should adjust these values to your environment.

JAVA_OPTS='-Xms4000m -Xmx7000m'

I hope this helps.

1 Like

Thank @jaime.bosque , for your assistance.

it was my problem. I didn’t put the “export” word in dhis.conf like this:

export JAVA_HOME='/usr/lib/jvm/java-11-openjdk-amd64/'
export JAVA_OPTS='-Xms4000m -Xmx7000m'
export DHIS2_HOME='/home/dhis/config'