Skip to main content

Getting started with DHIS2


You can start developing a DHIS2 app on OSX, Windows or Linux using Docker and the DHIS command line interface (CLI). In this guide, you will install the prerequisites, start up a local DHIS2 instance and create a new app. Your app will connect to the local DHIS2 instance.

Installing prerequisites

If you are using Debian Linux,

  1. Follow the DHIS2 Docker guide to install the prerequisites

If you are using OSX or Windows,

  1. Install Docker
  2. Install yarn
  3. From the command line or terminal, install the DHIS2 CLI globally
yarn global add @dhis2/cli

Now that you have installed Docker and the CLI you are ready to start up a local DHIS2 instance.

Starting a local DHIS2 instance

  1. From the terminal, start up DHIS2 and seed the database
d2 cluster up 2.35.0 --db-version 2.35 --seed
  1. From the browser, navigate to http://localhost:8080. If DHIS2 is running, you should see the following page:

Login Page

Sign in as admin (username) and district (password). If you can load DHIS2 in the browser, you are ready to create a new app.

Creating a new app

  1. From the terminal, create a new DHIS2 app called "my-app"
d2 app scripts init my-app
  1. Change directories to /my-app and start the app
cd my-app && yarn start

Connecting your app to DHIS2

  1. From the browser, navigate to http://localhost:3000. You will see the following page:

  1. Enter your DHIS2 server URL and the username and password of the default admin user
server: http://localhost:8080
username: admin
password: district
  1. You will see the default admin user name and a welcome message

Congratulations! You are ready to start developing a DHIS2 app 🎊

Next steps

Now that you have created a DHIS2 app and connected it to a local DHIS2 instance you can learn more about developing apps on DHIS2.