Skip to main content

How to setup Instant OpenHIE on Windows with WSL

info

The Instant OpenHIE architecture, codebase, and documentation are under active development and are subject to change. While we encourage adoption and extension of the Instant OpenHIE framework, we do not consider this ready for production use at this stage.

Overview#

The purpose of this how-to guide is to help set up a complete development environment for Instant OpenHIE on Windows using WSL 2 including VSCode and Docker setup.

WSL is the Windows Subsystem for Linux which allows Windows users to interact with GNU/Linux environment directly from Windows. More about WSL can be found here:

Prerequisites#

System requirements:

  • Stable internet connection with high download speeds.
  • 16GB RAM.
  • At least 20GB free space.

To make use of WSL 2, you must be running Windows 10.

  • For x64 systems: Version 1903 or higher, with Build 18362 or higher.
  • For ARM64 systems: Version 2004 or higher, with Build 19041 or higher.
  • Builds lower than 18362 do not support WSL 2. Use the Windows Update Assistant to update your version of Windows.

The version and build number can be checked in the Windows System Information by simply typing "System Information" into Windows search and looking at the Version item under the System Summary.

1. Install WSL#

Follow the Manual steps on the Microsoft website to install the WSL feature for Windows:

Ensure you upgrade to WSL 2 for performance reasons.

2. Linux Distribution Setup#

If you haven't already done this as part of the step 1 above, you will need to create a user account and password for the Linux Distribution, the following link can assist with that:

Limit the RAM usage of WSL to prevent the Windows LxssManager service from hogging all of the computer resources. The following article helps to achieve this:

The recommended .wslconfig file to use:

.wslconfig
[wsl2]
memory=8GB # Limits VM memory in WSL 2 to 8 GB
processors=5 # Makes the WSL 2 VM use two virtual processors

When using WSL 2 it is better to store files in the Linux subsystem file system rather than in the Windows file system for performance reasons. The easiest way to do this is to simply clone repositories and other files to the $HOME (~) directory on the Linux subsystem.

The current suggested Linux distribution is Ubuntu 20.04 LTS

3. Git Setup#

Many Linux distributions come with git out of the box, but if required, the following commands will install git:

sudo apt-get update
sudo apt-get install git

4. Docker Desktop Setup#

Download and install Docker Desktop from:

Docker Desktop installs docker-compose by default and sets up docker without sudo in the Linux terminal

5. Source Code & Development Environment Setup#

Download and install VS Code from:

Install the Remote - WSL VS Code extension for ease of working with your newly installed WSL 2 environment.

Reload VS Code and open the terminal (default shortcut is Ctrl + ~), you should see the bash terminal come up and have an indication of the linux distribution that's running on the bottom left of the VS Code window. e.g.

WSL: Ubuntu-20.04

Install npm and yarn

sudo apt-get install npm
npm install yarn

Clone the Instant OpenHIE repository into the $HOME directory (or any sub-directory of $HOME).

For HTTPS:

git clone https://github.com/openhie/instant.git

For SSH:

git clone git@github.com:openhie/instant.git

Tip: Do not clone the repository or store any important files in the /mnt/wsl directory as this directory gets cleared every time the Windows LxssManager service gets restarted (every time you restart Windows).

Build the Docker images using:

yarn docker:instant build
yarn docker:instant init core

To test the installation, navigate to http://localhost:9000/ in your preferred browser and login to the OpenHIM console to confirm that everything is up and running.

Useful Links#

Edit this page