WSL Web Development Setup
I have been using Windows + WSL2 for my web development environment for many years now.
Over time I gathered some helpful resources for setting up such development environment, so I decided
to write this post to have a reference for myself and you, dear reader!
It shows how to set up
- WSL itself
- git-related tooling
- prerequisites to be able to install, build, etc. codebases using the Node.js ecosystem
- and, optionally, additional things
Basic setup #
-
Open PowerShell as administrator and run:
wsl --install
-
Restart your machine.
-
Run "Ubuntu" from the start menu to start an Ubuntu terminal.
-
It will ask for a username and password - choose some.
-
I like to not having to enter the password when running things in the WSL distribution, do the following to remove it:
-
Run:
sudo visudo
-
At the bottom of the file, add the following line (replace
<username>
with your chosen username):<username> ALL=(ALL) NOPASSWD: ALL
-
Press
CTRL+X
to exit nano and it will prompt you to save. -
Close the terminal and start a new one (by running "Ubuntu" from the start menu).
-
-
Update and upgrade all packages:
sudo apt update && sudo apt upgrade
Git and GitHub SSH #
-
Update git to the latest version and add support for git LFS:
sudo apt-get install git sudo apt-get install git-lfs git lfs install
-
Configure git:
git config --global user.name "Your Name" git config --global user.email "your_email@example.com"
-
Create a SSH keypair and add the private key to ssh-agent in Ubuntu (based on ):
# Generate a SSH keypair # When asked to enter a file to save the key, I recommend to choose a different filename. # For GitHub instead of "/home/pkerschbaum/.ssh/id_rsa" I would choose "/home/pkerschbaum/.ssh/id_rsa_github" # When asked for a passphrase, I typically omit that. ssh-keygen -t ed25519 -C "your_email@example.com" # Start the ssh-agent in the background eval "$(ssh-agent -s)" # Add your SSH private key to the ssh-agent ssh-add "/home/pkerschbaum/.ssh/id_rsa_github" # copy the public key in Windows clipboard cat "/home/pkerschbaum/.ssh/id_rsa_github.pub" | clip.exe
-
Add the public key of your new SSH keypair to your GitHub account (note: you must check out the GitHub repositories via SSH then, not via HTTPS):
- Open new SSH key of your GitHub settings
- Title: I recommend to combine the name of your PC with "WSL", like
ZEPHYRUS-M16 WSL
. - Key type: Keep
Authentication Key
- Key: Use the content of the clipboard (= the public key).
-
Sometimes after I have set up WSL it had strange network issues for outbound connections.
I found some GitHub issues regarding that and one of them mentioned a misconfigured network interface.
That's why nowadays I always do the following one time after setting up WSL (based on ):-
Start PowerShell as administrator.
-
List the network interfaces of Windows:
netsh interface ipv4 show subinterfaces
-
There should be an interface called
"vEthernet (WSL)"
. Also you must have some WiFi interface, in my case it is called"WiFi"
. Both interfaces should have the same "MTU" value.
If not, run this:netsh interface ipv4 set subinterface "vEthernet (WSL)" mtu=<MTU-value-of-wifi-interface> store=persistent wsl --shutdown
-
Node.js (and related tools) #
-
Instead of installing Node.js directly I like to use
nvm
to be able to have multiple versions of Node.js installed at the same time (you can read more here: ).
Run this to installnvm
:# replace v0.39.3 by the newest version # you can look it up here: https://github.com/nvm-sh/nvm/releases curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.3/install.sh | bash
-
To be able to compile npm packages which include native C++ addons, via
node-gyp
, we need to install a few things:sudo apt-get install build-essential g++ libx11-dev libxkbfile-dev libsecret-1-dev python-is-python3
-
npm has a feature to complete commands via the tab key, so let's enable that:
npm completion >> ~/.bashrc
Additional things #
-
Docker: Choose one of the following:
- Docker Desktop: This is the recommended option because everything just works.
- Install Docker directly in WSL Ubuntu: Drawbacks are that there is no support for starting containers from Windows directly and multi-platform builds are not possible with this option.
Also recommended:
-
Install hadolint:
# replace v2.10.0 by the newest version # you can look it up here: https://github.com/hadolint/hadolint/releases wget -O /bin/hadolint https://github.com/hadolint/hadolint/releases/download/v2.10.0/hadolint-Linux-x86_64
-
VS Code: Install the extension, then you can run in an Ubuntu terminal
code .
to start VS Code in that folder. -
Certain Node.js and Ubuntu combinations can lead to errors when Node.js
crypto
APIs are used. In case you get an error along the lineserror:25066067:DSO support routines:dlfcn_load:could not load the shared library
when running Node.js code you can do this: . -
If there are connection issues (even after fixing the MTU value of the WSL network interface, what we did above) you might need to change the DNS server: .
-
Some tips:
- Run
explorer.exe .
in an Ubuntu terminal to open the Windows Explorer at that directory path. - Run
wsl --shutdown
in Windows CMD or PowerShell to shutdown the WSL instance.
- Run