/wsl

Windows Subsystem for Linux

.img/logo_wsl.png

Windows Subsystem for Linux

Let's bring the full power of Linux to your Windows computer!

We will cover everything that's needed to:

  • Install Docker on WSL without the need of Docker Desktop
  • Allow the WSL session (and Docker) to run in the background
  • Start WSL (and Docker) automatically after reboot

Table of Contents

Introduction

Supplemental


0. Preface

Windows Subsystem for Linux is literally the best thing from Microsoft since Clippy; for a quick summary see: https://www.youtube.com/watch?v=UMQ5GQix0rs

When WSL is combined with Docker that runs locally in the background, you now have the ease of Windows productivity applications alongside a Linux-based development environment

Back to Top


1. Requirements

Hardware

  • Your CPU must support virtualization and be enabled in the BIOS:
    • Intel calls this Intel Virtualization Technology
    • AMD calls this SVM Mode

Windows 10

.img/fig_01_01.jpg

  • You must enable Hyper-V in "Turn Windows features on or off":
    • NOTE: This example below shows that Hyper-V cannot be turned on due to virtualization being disabled in the firmware (i.e. BIOS)

.img/fig_01_02.jpg

Command Line Interface (CLI)

Back to Top


2. WSL1 vs. WSL2

NOTE: If you already have WSL1 installed and you're upgrading to WSL2, you will lose everything (e.g. SSH keys, AWS configs, Git credentials, etc.) if you do not copy them over to your Windows partition

  • If you know you don't have WSL1 or 2 installed, you will have to install from scratch
  • If you run the following command in PowerShell (as Administrator) and get something other than a "2", you will need to upgrade from WSL1 to WSL2
> wsl --list --verbose
  NAME            STATE           VERSION
* Ubuntu-20.04    Running         2
  • Otherwise, if you have WSL2 but haven't installed Docker (without Docker Desktop), skip ahead to here

Installing WSL2 from Scratch

  • Open PowerShell as Administrator
  • Install WSL with this command:
> dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart
  • Enable the Virtual Machine Platform optional feature:
> dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart
> wsl --set-default-version 2
For information on key differences with WSL 2 please visit https://aka.ms/wsl2
The operation completed successfully.

.img/fig_02_01.jpg

  • Once installed, start the Ubuntu CLI and Windows will finish installation
  • You will need to setup a username and password

Upgrading WSL1 to WSL2

  • Back up everything you need to into your Windows partition (SSH keys, etc.)
  • Uninstall your current WSL Linux distribution in "Apps & features":

.img/fig_02_02.jpg

  • Now install WSL2 from scratch
  • Remember to copy everything back over to your new home directory and change ownership (i.e. chown) and permissions (i.e. chown) as appropriate

Back to Top


3. WSL2 Internet Access

  • The current release of WSL2 (as of 2022-02-19) may need additional configuration to allow internet connectivity within the CLI
  • Test the following in the WSL2 CLI:
$ ping google.com
  • If after 10-20 seconds you do not get a response, continue in this section, if you do see a response, move onto section 4. CLI Docker

Configuration Changes

Back to Top


4. CLI Docker

NOTE: You must have internet working within WSL2 from section 3. WSL2 Internet Access

We will now install CLI Docker by itself without the need for Docker Desktop

Install and Test Installation

  • Update, upgrade, and install Docker:
$ sudo apt update && sudo apt -y upgrade && sudo apt -y install docker.io
  • Add you username to the docker group and exit and log back in for it to take effect:
$ sudo usermod -aG docker $USER && exit
  • Test Docker to make sure the "hello-world" image downloads and container execution is successful:
$ docker run --name hello-world hello-world
.
.
.
Hello from Docker!
This message shows that your installation appears to be working correctly.
.
.
.

Configure Docker to Start on WSL Startup

  • Add the following lines at the bottom of the file to allow sudo docker commands to run in the background and save:
    • Replace "<USERNAME>" with you actual username in the file
$ sudo visudo
.
.
.
<USERNAME> ALL=(ALL) NOPASSWD: /usr/bin/dockerd
  • Add the following lines at the bottom of the file to start Docker when WSL starts
$ nano ~/.bashrc
.
.
.
RUNNING=`ps aux | grep dockerd | grep -v grep`
if [ -z "$RUNNING" ]; then
    sudo dockerd > /dev/null 2>&1 &
    disown
fi

Test to Confirm WSL and Docker Does Not Run in Background

  • Download the following vanilla NGINX webserver and navigate to the webpage locally:
    • This commad will download the Docker image and run a container with it
$ docker run -it --rm -d -p 80:80 --name nginx_container nginx
  • Navigate to "localhost" on your browser and you should see the NGINX splash page:

.img/fig_03_01.jpg

  • Now close your WSL console window and this will cause the WSL session to terminate (along with Docker)
  • After a few seconds, refresh the webpage and you will see that it cannot display since the NGINX webserver container is offline:
    • NOTE: Your browser may be displaying an offline cached version of the unreachable webpage if you do still see the same thing after refresh

.img/fig_03_02.jpg

  • Start back up a new WSL window, and restart the NGINX container:
$ docker restart nginx_container
  • After a few seconds, refresh the webpage and you will see that the splash page displays again:

.img/fig_03_03.jpg

This confirms that WSL and Docker are not running in the background when you close the WSL console and end the WSL session, we will enable running WSL (and Docker) in the background next

Back to Top


5. Special WSL Configuration

  • Start Powershell (as Administrator) and create a vbs script and open it in notepad:
> echo "" > $HOME\run_wsl2_at_startup.vbs
> notepad $HOME\run_wsl2_at_startup.vbs
  • Paste the following in the script for Ubuntu 20.04:
set object = createobject("wscript.shell")
object.run "wsl.exe --distribution Ubuntu-20.04",0
  • Open Task Scheduler and Create Basic Task
    • Name the task "WSL2" with description "Windows Subsystem for Linux 2", click Next
    • Select "When the computer starts", click Next
    • Select "Start a Program", click Next

.img/fig_04_01.jpg

  • Specify Action
    • Copy and paste path into "Program/Script" field, "%USERPROFILE%\run_wsl2_at_startup.vbs", click Next
    • Check "Open the properties dialog for this task when I click Finish", click Finish
  • General Tab
    • Select "Run Whether User Is Logged On or Not"
    • Select "Run With Highest Privileges"
  • Specify Trigger
    • Click "Triggers" in the top bar → highlight "At Startup" → Click Edit
    • Check "Delay Task For" and enter "30 Seconds", click OK
  • Settings Tab
    • Unselect "Stop the Task if It Runs Longer Than", click OK
  • Restart computer
  • Without starting the WSL console after reboot, confirm that WSL is running (as "wsl") in PowerShell by executing:
> get-process

.img/fig_04_02.jpg

Test to Confirm WSL and Docker Does Are Running in Background

  • Ensure that the NGINX container from the previous step is running, in WSL console execute:
$ docker restart nginx_container
  • Navigate to "localhost" on your browser and you should see the NGINX splash page:

.img/fig_04_03.jpg

  • Now close your WSL console window; previously this would cause the WSL session to terminate (along with Docker)
  • After a few seconds, refresh the webpage and you will see that it is still displaying:

.img/fig_04_04.jpg

Congratulations, this confirms that the WSL session and Docker are still running in the background even when you close the WSL console

Back to Top


Other Resources

Description Link
Other reasons to use WSL2 over WSL1 https://docs.microsoft.com/en-us/windows/wsl/compare-versions
License for Docker Engine (Apache v2.0) https://docs.docker.com/engine/#licensing
License for Docker Desktop (not installed here) https://docs.docker.com/subscription/#docker-desktop-license-agreement

WSL2-Capable Linux Distributions

  • Alpine WSL
  • Debian GNU/Linux
  • Fedora Remix for WSL
  • Kali Linux
  • openSUSE Leap 15.1
  • Pengwin
  • Pengwin Enterprise
  • SUSE Linux Enterprise Server 12 SP5
  • SUSE Linux Enterprise Server 15 SP1
  • Ubuntu
  • Ubuntu 16.04 LTS
  • Ubuntu 18.04 LTS
  • Ubuntu 20.04 LTS

Back to Top


Troubleshooting

Issue Solution
"It's not working!" This concise tutorial has distilled hours of sweat, tears, and troubleshooting; it can't not work

Back to Top


Acknowledgments

Back to Top


Copyright © 2022-∞ Athit Kao, Terms and Conditions