Windows 10 with WSL2

Introduction

Windows 10 now has Linux available internally via WSL2 (Windows Subsystem for Linux v2). WSL2 runs a real Linux kernel and is much faster than the first iteration, WSL1, however it is still noticeably slower than Linux installed on a 'bare metal'.

Taxonworks can be developed using WSL2 "natively". This document describes how to set everything up starting with enabling WSL2 on Windows 10.

You will NOT need Docker Desktop for this installation.

Preparation

Note: The installation procedure changes with time while WSL2 matures. This section describes installation procedure for Windows 10 October 2020 edition.

  • Run all Windows updates to make sure you are at the latest Windows 10 version.

  • Install Windows Terminal (optional)

    Windows Terminal is an Open Source project from Microsoft that provides a pretty nice terminal emulator. I would say the quality of it is approaching the quality of popular terminal emulators on Mac and Linux. It is highly configurabele and allows to run PowerShell, CMD, and Linux.

    To install it, open Windows Store app and search for Windows Terminal.

    To make Linux experience more convenient (for example starting from Linux home directory on Ubuntu, or using ligatures after installing Fira Code) you can modify Windows Terminal configuration (it is just a JSON text) similar to this example.

  • Install Visual Studio Code (optional)

    WSL2 does not have native support for graphical programs yet (it is planned). However Visual Studio Code, a popular code editor, supports a transparent "bridge" to WSL Linux. You can download it at https://code.visualstudio.com/download

    VS Code has several useful plugins that I would recommend to install:

    • Ruby: for Ruby language support.
    • Ruby Solargraph: for adding "code intelligence" via Language Server for Ruby -- Solargraph gem.
    • WSL: for (almost) transparent work with WSL2 directories.
    • Containers: for working with code transparently (almost) via WSL and/or SSH
    • Docker: simplifies interacting with docker containers (needed only if Docker Desktop is also installed)

    Some of these plugins are installed on windows side, some on the WSL2 side. Usually hints from VS Code allow to make correct decision where to install what.

Install WSL2

Open PowerShell as administrator (standalone or as Windows Terminal) and type the following commands:

  • Enable WSL2

    dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

  • Enable Virtual Machine Platform

    dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

    Restart your computer.

  • Setup WSL v2 as default

    wsl --set-default-version 2

WSL troubleshooting

If something does not work, first open PowerShell and make sure you are running WSL v2, and now WSL v1

wsl -l -v

wsl -l -v
  NAME                   STATE           VERSION
* Ubuntu-20.04           Running         2
  docker-desktop         Running         2
  docker-desktop-data    Running         2

Here the command shows that Ubuntu-20.04 is running correctly, is the default distribution (has *), and runs WSL version 2.

If you do have WSL2 installed, you will get report for every linux distribution you have if it is running correctly and what WSL version it has. If you have only WSL1 installed you will get an error message.

Removing Linux distribution can be either done usual way via uninstall GUI that Windows provides (Ubuntu distro should appear there like a 'normal' app), or It can be done using PowerShell with wslconfig command

wslconfig /l
Windows Subsystem for Linux Distributions:
Ubuntu-20.04 (Default)
docker-desktop
docker-desktop-data

To change WSL from v1 to v2 for a distribution (for example for Ubuntu-20.04) using PowerShell

wsl --set-version Ubuntu-20.04 2

To remove Ubuntu-20.04 the command would be:

wslconfig /u Ubuntu-20.04

Install Linux Distro

There are several Linux distros available for WSL2, in our example we use Ubuntu 20.04.

Go to Microsoft Store app, search for Ubuntu, install and launch it. You will see it appearing in a separate terminal this time. You can customize it right in the terminal, or you can close it, and reopen it in Windows Terminal, where it will appear now as an option.

Once Ubuntu 20.04 is installed, open it in the Windows Terminal, run:

sudo apt update
sudo apt dist-upgrade

Install Postgresql database

Open Ubuntu bash in Windows Terminal

Add PostgreSQL source repository for apt-get.

echo "deb [arch=amd64] http://apt.postgresql.org/pub/repos/apt/ focal-pgdg main" | sudo tee -a /etc/apt/sources.list.d/pgdg.list
wget --quiet -O - https://www.postgresql.org/media/keys/ACCC4CF8.asc | sudo apt-key add -
sudo apt-get update

Install required packages.

sudo apt-get install -y postgresql-15 postgresql-contrib-15 libgeos-dev libproj-dev postgresql-15-postgis-3 postgresql-15-postgis-3-scripts libpq-dev cmake imagemagick libmagickwand-dev tesseract-ocr git meld curl libssl-dev

check postgresql version:

psql --version

When prompted supply the same password you will add later to config/database.yml.

sudo service postgresql start
sudo -u postgres createuser -s -d -P taxonworks_development

Change permissions for posgresql, you are changing 'peer' to 'trust' for the matched line.

sudo sed -i.bak 's/local\s*all\s*all\s*peer/local all all trust/'  /etc/postgresql/15/main/pg_hba.conf
sudo service postgresql restart

Now you should be able to start postgres, stop, ask for a status:

sudo service postgresql status
sudo service postgresql start
sudo service postgresql restart
sudo service postgresql stop

Import Nodesource GPG key

sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | sudo gpg --dearmor -o /etc/apt/keyrings/nodesource.gpg

Configure apt-get to point to newer Node packages

echo "deb [signed-by=/etc/apt/keyrings/nodesource.gpg] https://deb.nodesource.com/node_18.x nodistro main" | sudo tee /etc/apt/sources.list.d/nodesource.list

Install Node

sudo apt-get update
sudo apt-get install nodejs -y

Install virtual Ruby environment. You can follow Ubuntu 20.04 instructions for for installing rvm. Here I use an alternative rbenv package, which is more lightweight.

Install rbenv

Rbenv, like rvm, allows to run several versions of ruby at the same time.

git clone https://github.com/sstephenson/rbenv.git ~/.rbenv
git clone https://github.com/sstephenson/ruby-build.git ~/.rbenv/plugins/ruby-build
git clone https://github.com/rkh/rbenv-update.git ~/.rbenv/plugins/rbenv-update

to ~/.bashrc add:

export PATH=$HOME/.rbenv/bin:$PATH
eval "$(rbenv init -)"

Restart terminal. Now you should be able to install current Ruby and set it as default.

rbenv install 2.7.2
rbenv global 2.7.2
gem install bundler

Other useful commands

rbenv help
rbenv install --list
rbenv versions
rbenv upgrade

Install taxonworks

mkdir Projects
cd Projects
git clone https://github.com/SpeciesFileGroup/taxonworks.git
cd taxonworks

When you do cd taxonworks you will see a message regarding a particular version of Ruby. If it is not yet installed, install that version of Ruby with the command provided in the terminal. It will look something like: rbenv install 2.7.2.

gem install bundler

bundle
npm install

cp config/database.yml.example config/database.yml
cp config/secrets.yml.example config/secrets.yml

bundle exec rake db:create && bundle exec bin/rails db:environment:set RAILS_ENV=development

bundle exec rake db:schema:load && bundle exec rake db:test:prepare

Run the test suite, you may see some failures, but the vast majority should pass.

bundle exec rake

If you get to this point and tests are running, you can continue with Ubuntu 20.04 documentation.

To work with taxonworks code using VS Code, enter Linux terminal, go to taxonworks development directory and run:

code .

This command will open VS Code on Windows side, connected to Linux via WSL 'bridge'.