DHIS 2

DHIS 2 is a flexible information system for data capture, management, validation, analytics and visualization. It allows for data capture through clients ranging from Web browsers, Android devices, Java feature phones and SMS. DHIS 2 features data visualization apps for dashboards, pivot tables, charting and GIS. It provides metadata management and configuration. The data model and services are exposed through a RESTful Web API.

Overview

Issues can be reported and browsed in JIRA.

For documentation visit the documentation portal.

You can download pre-built WAR files from the continuous integration server.

You can explore various demos of DHIS 2 in the play environment.

For support and discussions visit the community forum.

For general info visit the project web page.

For OpenAPI documentation visit the Stoplight workspace.

For software developer resources visit the developer portal.

To contribute to the software read the contributor guidelines.

The software is open source and released under the BSD license.

Run DHIS2 in Docker

The following guides use Docker Compose to run DHIS2 using Docker.

A DB dump is downloaded automatically the first time you start DHIS2. If you switch between different DHIS2 versions and/or need to download a different DB dump you will need to remove the shared volume db-dump using

docker compose down --volumes

Pre-built Images

We push pre-built DHIS2 Docker images to Dockerhub. You can pick an <image name> from one of the following repositories:

• dhis2/core - images of the release and release-candidate DHIS2 versions. These images represent the stable DHIS2 versions, meaning they won't be rebuilt in the future.

• dhis2/core-dev - images of the latest development DHIS2 versions - branches master (tagged as latest) and the previous 3 supported major versions. Image tags in this repository will be overwritten multiple times a day.

• dhis2/core-canary - images of the latest daily development DHIS2 versions. We tag the last core-dev images for the day and add an extra tag with a "yyyyMMdd"-formatted date, like core-canary:latest-20230124.

• dhis2/core-pr - images of PRs made from https://github.com/dhis2/dhis2-core/ and not from forks. As forks do not have access to our organizations/repos secrets.

To run DHIS2 from latest master branch (as it is on GitHub) run:

DHIS2_IMAGE=dhis2/core-dev:latest docker compose up

Local Image

Build a DHIS2 Docker image first as described in Docker image. Then execute

docker compose up

DHIS2 should become available at http://localhost:8080 with the Sierra Leone Demo DB.

Demo DB

If you want to start DHIS2 with a specific demo DB you can pass a URL like

DHIS2_DB_DUMP_URL=https://databases.dhis2.org/sierra-leone/2.39/dhis2-db-sierra-leone.sql.gz docker compose up

using versions we for example publish to https://databases.dhis2.org/

Build process

This repository contains the source code for the server-side component of DHIS2, which is developed in Java and built with Maven.

See the contributing page to learn how to run locally.

Docker image

The DHIS2 Docker image is built using Jib. To build make sure to build DHIS2 and the web project first

./dhis-2/build-dev.sh

Run the image using

docker compose up

It should now be available at http://localhost:8080.

Customizations

Docker tag

To build using a custom tag run

mvn clean package -DskipTests -Dmaven.test.skip=true --file dhis-2/pom.xml \
    --projects dhis-web-server --also-make --activate-profiles jibDockerBuild \
    -Djib.to.image=dhis2/core-dev:mytag

For more configuration options related to Jib or Docker go to the Jib documentation.

Context path

To deploy DHIS2 under a different context then root (/) configure the context path by setting the environment variable

CATALINA_OPTS: "-Dcontext.path='/dhis2'"

DHIS2 should be available at http://localhost:8080/dhis2.

Overriding default values

You can create a local file called docker-compose.override.yml and override values from the main docker-compose.yml file. As an example, you might want to use a different version of the Postgres database and run it on a different port. More extensive documentation of this feature is available here. Using the override file you can easily customize values for your local situation.

version: "3.8"

services:
  db:
    image: postgis/postgis:14-3.3-alpine
    ports:
      - 127.0.0.1:6432:5432

DHIS2_HOME

Previously, the Docker image was built with environment variable DHIS2_HOME set to /DHIS2_home. This is not the case anymore, instead DHIS2_HOME will fallback to its default /opt/dhis2. You can still run the Docker image with the old behavior by setting the environment variable DHIS2_HOME like

    environment:
      DHIS2_HOME: /DHIS2_home

in a docker-compose.override.yml file. Alternatively, you can pass the system property -Ddhis2.home directly from the command line. You need to ensure that this DHIS2_HOME is writeable yourself!