Local Debian DHIS2 instance in Windows 10

Installing a local DHIS2 Debian instance on Windows 10 is fairly easy and after meeting the requirements, all one needs to do is follow the official DHIS2 Docker guide (with minor changes that are explained at the end of this post); therefore, to get started make sure you have the following requirements:

Requirements:

WINDOWS 10

There are two main things that need to be configured in your Windows 10. The first is to make sure that you are using the minimum version and build number. According to Microsoft:

  • For x64 systems: Version 1903 or higher, with Build 18362 or higher.
  • For ARM64 systems: Version 2004 or higher, with Build 19041 or higher.

To know your version and build number, using CMD enter:

ver

or by using Windows key + R then type winver:

Second, make sure you enable Windows Subsystem for Linux (WSL) feature. Either by searching for “Turn Windows features on or off” in the start menu:

Or you can enable WSL by entering the following script in Powershell as Administrator:

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux x /all /norestart


Don’t restart yet so you can Update to WSL2. :grin:

Windows Subsystem for Linux

The required version of Windows Subsystem for Linux is WSL2, which means you’ll have to update WSL. For the update to be successful, you’re going to have to enable the virtual machine feature. To enable the virtual machine platform on Windows 10, open Powershell as administrator and enter the following script:

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

Update to WSL2

To update you’re going to have to download the update package from Microsoft’s website: click to download update for x64 machines, or if you are using an ARM64 machine, click here to download update for ARM64 machines


To know what kind of machine you are using, open CMD and enter:

systeminfo | find "System Type"

Set WSL2 as your default version

To choose your default WSL version, start Powershell as Administrator and enter:

wsl --set-default-version 2

Install Linux Debian

Although it is possible to install other linux distributions, I’ve chosen Debian because it is the one used in the official DHIS2 Docker install guide.

Click here to go to Microsoft Store and install Debian

Docker for Desktop

Even though we are not going to be using DHIS2 on Windows 10; however, Docker for Desktop enables integration with WSL. First, download Docker for Desktop in your Windows 10, click here. Second, after downloading Docker for Desktop, open the main window, click on settings, and make sure the following settings are enabled.

  • Use the WSL 2 based engine

  • Enable integration with my default WSL distro
  • Enable Debian

After completing all the requirements above, now you are ready to follow the official DHIS2 Docker User Guide. First open your Debian terminal from the start menu:

You’re going to start by creating a default UNIX user account, and make sure you enter a new password that you can remember because it is going to be the root password for your account and you’re going to need it during the installation.

If you want to know your version number you can type:

cat /etc/os-release

Open the DHIS2 Docker Guide (click here), all commands in the guide should work, but when you get to the command systemctl because of the way WSL functions, we can’t use systemctl to start docker instead we use the command service. For example, instead of using “sudo systemctl start docker” we’re going to use “sudo service docker start.” However, do use “sudo systemctl enable docker” because it works.

All other steps should work fine until you get to the Install D2 CLI section there is a minor change that you need to make. Instead of using tee, we’re going to use nano to edit the files we want to append into. For example, use “nano ~/.config/d2/config.js” then add to the file everything after <<EOF and before the EOF at the end of the tee command used in the guide.

Finally when you get to the command before the last: d2 cluster up dev

If you run it and it says: Couldn’t connect to Docker daemon at http+docker://localhost - is it running?

Then make sure that the Docker for Desktop software in Windows 10 is open and in the WSL terminal run the command:

sudo service docker start

Finally just as it has been written in the Developers Guide page “Getting Started with DHIS2,” you’re going to do the following:

From the WSL terminal, start up DHIS2 and seed the database

d2 cluster up 2.35.0 --db-version 2.35 --seed

From the browser in Windows 10, navigate to http://localhost:8080

It should work fine unless you’ve installed a software that’s using the port 8080!

Sign in as admin (username) and district (password). Now you can use this instance in Windows 10 and still benefit from all the documentation, guides, and services that have been set for Debian.

4 Likes

The method above is for developers; therefore, there will be two instances running:


As you can see from the image above to list all the clusters, we use the command:

d2 cluster list

By default both clusters are going to want to use Port 8080, so what I did was turn one down. In the terminal enter the code:

d2 cluster down 2.35.0

Then when running it up, I entered the command with another port number:

d2 cluster up 2.35.0 --port 8081

Now I can run the developer version as well as the latest Sierra Leone 2.35.0 version.

2 Likes

Very nice guide @Gassim !

1 Like

You’re welcome, and thank you for your support. Thanks to the DHIS2 Developers portal, the guides there were really helpful. I tried many times on my own until I followed the guide on Debian, the whole process came together and it worked well for me.