Setting Up DHIS2 Locally

Two containers run side by side on your own machine. One is the database, the other is DHIS2 itself. They talk to each other over a private network, and your browser reaches DHIS2 on one port.

1. 1The database. PostGIS, which is PostgreSQL with the map extension DHIS2 needs.
2. 2DHIS2. The application itself, version 2.42.1 here.
3. 3The network. A private bridge. DHIS2 finds the database by the name database.
4. 4Your browser. http://localhost:8010, which is the port opened in the compose file.

Docker is the only thing you install. DHIS2 and the database then run inside it, and nothing else is added to your machine.

Git is only used to copy the two setup files onto your machine.

Every command below talks to Docker. If Docker Desktop is not running, the terminal answers with an error no matter how correct your file is, so open Docker first and wait for it to finish starting, then open PowerShell or your terminal.

You need Docker Desktop and git. On Windows, Docker Desktop needs WSL2 turned on.

1. 1docker --version. If this fails, install Docker Desktop first.
2. 2docker compose version. Note the space. Old installations use docker-compose with a hyphen.

git clone https://github.com/mohamedsillahkanu/dhis2-local-set-up.git
cd dhis2-local-set-up

1. 1git clone. Copies the folder to your machine.
2. 2cd. Every command below is run from inside this folder.
3. 3The files. docker-compose.yml describes the containers, dhis.conf tells DHIS2 how to reach the database.

This file is the whole setup. Nothing is installed on your machine except Docker.

services:
  database:
    image: postgis/postgis:13-3.3-alpine
    container_name: dhis2_test_db
    environment:
      POSTGRES_USER: dhis
      POSTGRES_PASSWORD: dhis
      POSTGRES_DB: dhis2
      PGDATA: /var/lib/postgresql/data/pgdata
    volumes:
      - dhis2-test-db-data:/var/lib/postgresql/data
    ports:
      - "5433:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U dhis -d dhis2"]
      interval: 10s
      timeout: 5s
      retries: 5
    restart: unless-stopped
    networks:
      - dhis2-test-network

  dhis2:
    image: dhis2/core:2.42.1
    container_name: dhis2_test
    depends_on:
      database:
        condition: service_healthy
    environment:
      DHIS2_DATABASE_HOST: database
      DHIS2_DATABASE_NAME: dhis2
      DHIS2_DATABASE_USERNAME: dhis
      DHIS2_DATABASE_PASSWORD: dhis
      DHIS2_HOME: /DHIS2_home
    ports:
      - "8010:8080"
    volumes:
      - dhis2-test-data:/DHIS2_home
      - ./dhis.conf:/opt/dhis2/dhis.conf
    restart: unless-stopped
    networks:
      - dhis2-test-network

volumes:
  dhis2-test-db-data:
    name: dhis2-test-db-data
  dhis2-test-data:
    name: dhis2-test-data

networks:
  dhis2-test-network:
    name: dhis2-test-network
    driver: bridge

Five lines. They tell DHIS2 which database to use and how to sign in to it.

connection.dialect = org.hibernate.dialect.PostgreSQLDialect
connection.driver_class = org.postgresql.Driver
connection.url = jdbc:postgresql://database:5432/dhis2
connection.username = dhis
connection.password = dhis

Everything from here depends on one question: is the DHIS2 image already on this machine? Ask Docker rather than guessing.

docker images | grep -E "dhis2|postgis"

1. 1The command. Lists the images stored on your machine.
2. 2dhis2/core 2.42.1. The version the compose file asks for. It must match exactly.
3. 3postgis 13-3.3-alpine. The database image.

The whole sequence, run from inside the cloned folder. The pull is the slow part, about 1 GB, and it happens once on this machine.

1. 1docker compose pull. Fetches both images named in the compose file.
2. 2The database image. Small, under 300 MB.
3. 3The DHIS2 image. About 1 GB. This is the line that takes the time.

1. 1up -d. Starts both in the background.
2. 2The database. Healthy before DHIS2 is allowed to start.
3. 3DHIS2. Started, but not ready yet.
4. 4ps. The quickest check on what is running.

1. 1logs -f. Follows the log as it is written.
2. 2Connected to database. Proof that dhis.conf is right.
3. 3Server startup. The line you are waiting for.
4. 4Ctrl + C. Stops watching. The containers keep running.

1. 1The address. localhost with the left port from the compose file.
2. 2Username. admin.
3. 3Password. district.
4. 4Log in. An empty DHIS2, ready for Topic 1.

Nothing is downloaded. The same commands as Scenario 1 without the pull. If the volume already holds a database, the start takes seconds rather than minutes.

1. 1The command. Lists what is stored locally.
2. 2The version. 2.42.1 must match the image line in docker-compose.yml.
3. 3up -d. Straight to starting, with no download.

1. 1up -d. The same command as Scenario 1.
2. 2The database. Healthy first.
3. 3DHIS2. Started.
4. 4ps. Both containers listed.

Four commands cover almost everything.

docker compose up -d        # start
docker compose down         # stop, keep the data
docker compose logs -f dhis2 # watch the log
docker compose restart dhis2 # restart DHIS2 only

1. 1down. Stops and removes the containers. The volumes, and therefore the data, stay.
2. 2up -d again. Starts from where you left off, in seconds this time.
3. 3down -v. Removes the volumes too. Everything you entered is gone. Use it only to start clean.

1. 1Ports are not available. Another program already uses 8010.
2. 2The fix. Change the left number only, for example 8011:8080, then up -d again.

The instance is empty. Nothing in DHIS2 can be built until the organisation unit hierarchy exists, so go on to Topic 1 and create it, by hand or from the CSV file provided there.