← Back to the hackathon home
Topic 2 of 18

Setting Up DHIS2 Locally

Step by Step Guide: From an Empty Laptop to DHIS2 Running in Your Browser

Purpose of this guide

Every other topic needs a DHIS2 to work in. Follow the steps below in order, and at the end you will have your own DHIS2 running on your laptop, ready for Topic 3.

Before You Start: Install Docker Desktop and Git

Install these two programs first. Accept the default options, and restart your computer if the installer asks you to.

Why Docker? DHIS2 needs Java, a web server and a PostgreSQL database to run. Docker runs all of these for you inside ready made containers, so you do not install or configure any of them yourself, and everyone in the hackathon gets exactly the same working setup.

Why Git? The setup files are kept on GitHub. Git copies them onto your laptop with one command, so everyone starts from the same files. On Windows, Git also gives you Git Bash, the window where you type the commands.

ProgramDownload it here
Docker Desktop (Windows and Mac)https://www.docker.com/products/docker-desktop/
Git Bash (Windows)https://git-scm.com/download/win
Git (Mac)https://git-scm.com/download/mac
Step 1: Start Docker Desktop

Open Docker Desktop and wait until it says Running. Leave it open while you do every step below. If Docker Desktop is not running, none of the commands will work.

Step 2: Open Git Bash
Windows: Start menu → Git Bash   |   Mac: Applications → Utilities → Terminal

Type each command in the steps below into this window, then press Enter.

Step 3: Download the Setup Files

Copy the setup folder onto your laptop.

git clone https://github.com/mohamedsillahkanu/dhis2-local-set-up.git
Step 4: Go Into the Folder

Move into the folder you just downloaded. Run every command after this from inside it.

cd dhis2-local-set-up
Figure 1. Downloading the setup files and going into the folder. This picture was drawn for the guide. Your screen will show your own paths and timings.
  1. 1git clone. Copies the setup folder onto your laptop.
  2. 2cd. Moves into the folder. Stay here for the rest of the steps.
  3. 3The setup files. They are ready to use. You do not need to change anything in them.
Step 5: Download DHIS2 and Its Database

This downloads about 1 GB, so it takes five to fifteen minutes depending on your internet. You only do it once on this laptop.

docker compose pull
Figure 2. The download. This picture was drawn for the guide. Your screen will show your own paths and timings.
  1. 1docker compose pull. Downloads DHIS2 and its database.
  2. 2The database. The smaller download.
  3. 3DHIS2. About 1 GB. This is the part that takes the time.
Step 6: Start DHIS2

Start DHIS2 and its database, then check that both are running.

docker compose up -d
docker compose ps
Figure 3. Starting DHIS2 and checking it. This picture was drawn for the guide. Your screen will show your own paths and timings.
  1. 1docker compose up -d. Starts DHIS2 and its database in the background.
  2. 2The database. It should say healthy.
  3. 3DHIS2. Started, but not ready yet.
  4. 4docker compose ps. Shows what is running.

You can also see them in Docker Desktop. Open Containers, and both should show a green dot.

Docker Desktop showing the DHIS2 containers running
Figure 4. The same check in Docker Desktop, under Containers. Screenshot from a laptop running this setup.
  1. 1dhis2-local-set-up. The group holding both containers. A green dot means it is running.
  2. 2dhis2_test. DHIS2 itself.
  3. 3dhis2_test_db. The database.
  4. 48010:8080. Click this link to open DHIS2 in your browser.
Step 7: Wait for DHIS2 to Finish Starting

The first start takes three to ten minutes. Watch it with this command, and wait for the line Server startup. Then press Ctrl + C to stop watching. DHIS2 keeps running.

docker compose logs -f dhis2
Figure 5. Waiting for the first start. This picture was drawn for the guide. Your screen will show your own paths and timings.
  1. 1docker compose logs -f dhis2. Shows what DHIS2 is doing as it starts.
  2. 2Connected to database. DHIS2 found its database.
  3. 3Server startup. The line you are waiting for.
  4. 4Ctrl + C. Stops watching. DHIS2 keeps running.
Step 8: Open DHIS2 in Your Browser

Open this address in your browser, and sign in with username admin and password district.

http://localhost:8010
The DHIS2 login page at localhost 8010
Figure 6. The DHIS2 login page. Screenshot from a laptop running this setup.
  1. 1The address. http://localhost:8010 in your browser.
  2. 2Username. admin.
  3. 3Password. district.
  4. 4Log in. An empty DHIS2, ready for Topic 3.
Step 9: You Are Ready

You now have your own empty DHIS2. Change the admin password before anyone else uses it, then go on to Topic 3 to build the organisation units.

Need help? If you face any challenge with these steps, please email sillahmohamedkanu@gmail.com.
DHIS2 Hackathon, Topic 2: Setting Up DHIS2 Locally