Windows Setup

Overview

Linux based docker containers run faster within WSL2 compared to running them with Hyper-V. Consequently, this guide will walk you through setting up WSL2 on your local machine, install the dependencies required to spin up docker containers within WSL2, and setup the repositories required to get started with development at intelliHR.

Goals

1. Set WSL2 as default WSL version
2. Install Linux Distribution
3. Configure default distribution
4. Configure VSCode to use WSL2
5. Enter the WSL2 shell
6. Limit resources consumed by WSL
7. Setup Lapis, Graphie and SPA

Useful Resources

• What is WSL?
• What is Hyper-V?
• Why use WSL2?

Prerequisites

Your Windows machine should have the following programmes already provisioned

• Windows 10 version 2004 or above
• Docker Desktop Stable 2.3.0.2 or later release
• VSCode

Create a directory for your code to live

Before getting started, create a directory where you want all your code to live and cd into it. For example:

wsl #If you aren't already within wsl
cd ~
mkdir code
cd code

1. Set WSL2 as default WSL version

In PowerShell, run the following command

wsl --set-default-version 2

This will set any new Linux distributions you install to use WSL2 instead of WSL1.

See the WSL2 Installation Guide if you have any issues or for more information.

2. Install Linux Distribution

In the “Company Portal” app, install a Linux distribution of your choice.

The most common distribution we currently use is Ubuntu 20.04 LTS. Once installed, open Ubuntu 20.04 from the Start Menu and make sure to create a default UNIX user account by entering a username and password.

3. Configure default distribution

Depending on how you plan to run commands in WSL2 (see step 5), you might want to configure the distribution you installed in step 2 to be the default distribution.

In PowerShell, assuming you installed Ubuntu in step 2, run the following command

wsl --setdefault Ubuntu-20.04

See the WSL Configuration Guide if you have any issues or for more information.

4. Configure VSCode to use WSL2

• Launch VSCode and install the Remote WSL extension

5. Enter the WSL2 shell

In order to interact with the WSL2 environment, you will need to start the WSL daemon. This can be done in multiple ways:

• In PowerShell, run wsl (uses default distribution configured in step 3)
• Run the app downloaded from the company portal; for example, running the “Ubuntu” app
• Open a terminal in VSCode while you are in a folder open in the WSL2 environment
• Open a WSL2 tab in “Windows Terminal”, see the WSL2 Installation Guide for more info

Optional

Install the packages below if you encounter errors related to python, build essentials or git not being installed.

Ensure that apt-get command line tool is up to date

sudo apt-get update
sudo apt-get upgrade

Install Node.js LTS (v14.x)

If you wish to install a different version, then refer to this document.

curl -sL "https://deb.nodesource.com/setup_lts.x" | sudo -E bash -
sudo apt-get install -y nodejs

Install Python

sudo apt-get install python3.6

Alternatively, check with your teammates to see what version of python they are using.

Install build essentials

sudo apt-get install build-essential

Install git

sudo apt install git-all

Then, configure your git account.

git config --global user.name "Your Name"
git config --global user.email "your.email@intellihr.com"

6. Limit the resources consumed by WSL

By default, WSL will consume as much of your local machines resources as it can, slowing it down significantly. To fix this, we define a .wslconfig file to limit the amount of resources available to WSL.

• To start off, hit ctrl + alt + delete on your keyboard and click on Task Manager
• Click on More Details if the content is minimized
• Click on Performance > Memory and note down the maximum amount of Memory available to you
• Click on Performance > CPU and note down the number of Logical processors available to you
• Navigate to C:\Users\userName using the Windows File Explorer
• Create a new file called .wslconfig
• Open it with your editor of choice and paste the config below into it
• Replace <half-of-your-memory> and <half-of-your-logical-processors> with what you noted down earlier. For example, for a machine with 16GB Memory and 8 logical processors, set memory=8GB and processors=4

[wsl2]
memory=<half-of-your-memory>GB #Limits VM memory in WSL2
processors=<half-of-your-logical-processors> #Makes the WSL2 VM use 4 virtual processors

7. Setup Lapis, Graphite and SPA

Follow the Quick Start guide to setup Lapis, Graphite and SPA.

Common issues after setup

• There is a known issue with Windows 10 WSL2 builds where the virtual machine time is held static if a powershell window is left open and connected as the machine suspends (eg. closing a laptop lid whilst a powershell process is running).This causes the virtual machine system time to lag and become gradually more inaccurate. In many cases, this doesn’t affect local development, but should a service rely on an externally provided token (eg. AWS development accounts), this can result in false ’expired’ errors and similar.

This github issue is tracking the problem, and contains several approaches to addressing the problem, but not yet any permanent fixes - https://github.com/microsoft/WSL/issues/5324.