Develop your DHIS2 Web Apps in WSL Environment

[Gassim (AL-Gassim Sharaf Addin)]

In case you faced an issue building and running your dhis2 web apps while using Powershell or Command Prompt while on Windows, you’re adviced to use the Windows Subsystem for Linux. Furthemore, if you are used to using Visual Studio Code then you will not notice any difference between using it on Linux or on Windows.

Here are quick steps and references that will help you get started:

1. First, make sure that you have WSL2 in your system. Run in your terminal wsl -l -v so if you see under VERSION the number 2, then WSL2 is installed.

If WSL2 is not in your system then use the following guide to install it, click here

@Gassim

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 /all /norestart

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

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

2. Second, install a Linux system, I recommend to install Debian so you’re able to follow the developers guides on developers.dhis2.org (but if you already have Ubuntu then go for it!)

If you've not installed a linux system, you can use the following guide, click here

@Gassim

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

You’ll also find a good instruction there:

To keep your Debian environment up-to-date please use the following commands:

$ sudo apt update
$ sudo apt dist-upgrade

3. Third, Install VS Code and the Remote WSL extension, and when you do that two very important points to make sure you don’t miss:
   • check the Add to PATH option during installation
   • Install the Remote Development extension pack
   • Install Git (and this is very important so you can clone and use your projects in the WSL directory because if you use the Windows directory on WSL you will face performance issues)

You can use the following official guides to install VSCode and Git, click here

• To install VSCode (Get started using VS Code with WSL | Microsoft Learn)
• To install Git on WSL (Get started using Git on WSL | Microsoft Learn)

4. Finally, Once you have VSCode running with the remote-wsl-extension, you can type Ctrl+P > (or F1) and then type Remote-WSL. You will see a number of options but the first time, it’s recommended that you choose New Window in WSL and then use the terminal Ctrl+Shift+` to clone the git repository (if it’s already on github) to the WSL directory.

---

Thank you! Please feel free to comment and share updates or issues during this process. If you need more clarification on any of the instructions please post back!

Good luck!