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 #

  1. Open PowerShell as administrator and run:

    wsl --install

  2. Restart your machine.

  3. Run "Ubuntu" from the start menu to start an Ubuntu terminal.

  4. It will ask for a username and password - choose some.

  5. I like to not having to enter the password when running things in the WSL distribution, do the following to remove it:

    1. Run:

      sudo visudo

    2. At the bottom of the file, add the following line (replace <username> with your chosen username):

      <username> ALL=(ALL) NOPASSWD: ALL

    3. Press CTRL+X to exit nano and it will prompt you to save.

    4. Close the terminal and start a new one (by running "Ubuntu" from the start menu).

  6. Update and upgrade all packages:

    sudo apt update && sudo apt upgrade

Git and GitHub SSH #

  1. 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

  2. Configure git:

    git config --global user.name "Your Name"
git config --global user.email "your_email@example.com"

  3. Create a SSH keypair and add the private key to ssh-agent in Ubuntu (based on docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent?platform=linux):

    # 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

  4. 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):

    1. Open Add new SSH key of your GitHub settings
    2. Title: I recommend to combine the name of your PC with "WSL", like ZEPHYRUS-M16 WSL.
    3. Key type: Keep Authentication Key
    4. Key: Use the content of the clipboard (= the public key).

  5. 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 github.com/microsoft/WSL/issues/7254#issuecomment-1202299443):

    1. Start PowerShell as administrator.

    2. List the network interfaces of Windows:

      netsh interface ipv4 show subinterfaces

    3. 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

  1. 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: pkerschbaum.com/tidbits/multiple-vs-code-instances-with-separate-nodejs-versions).
    Run this to install nvm:

    # 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

  2. 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

  3. npm has a feature to complete commands via the tab key, so let's enable that:

    npm completion >> ~/.bashrc

Additional things #