Docker on Windows 10 Home with WSL2

The way we web engineers work has changed tremendously over the last few years. Working on your laptop with a single XAMPP or WAMP instance is not nearly enough anymore. With the microservices architecture needed and demanded everywhere, a better solution is needed on our workstations.

The Linux users have had access to Docker and Docker Compose, which provides a pretty lightweight and extremely efficient way to develop full-scale microservice applications on their local environments. However, Windows user did not have this luxury. Installing Docker Desktop as a hybrid of Docker and virtual machine was not the best solution. So in our company IdeaSpot we also tried installing VirtualBox, Ubuntu and use that guest Linux system to host Docker. On the pros side – that worked. On the cons side – what’s the point having Windows if you work on guest Ubuntu all the time.

The solution came with Docker providing a version for Windows 10 Home, utilizing the brand-new WSL2 (Windows Subsystem for Linux). In this post we will show you how we configured our system to allow efficient, best-practices approach to developing microservices-based web systems on Windows 10 Home with WSL2 and with Docker.

Enabling WSL2 Feature

In order to install Docker on Windows 10 Home you first need to enable the WSL feature. Go to Control Panel, search for enabling features and choose the two required ones:

Virtual Machine Platform
Windows Subsystem for Linux

Click OK and wait a while until the WSL feature is installed. Alternatively, if you prefer to type-in instead of clicking, use these 2 commands to enable WSL:

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

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

The next step is to install the WSL kernel. Currently there is no automatic way to do it. Follow the instructions here:

https://docs.microsoft.com/pl-pl/windows/wsl/install-win10#step-4—download-the-linux-kernel-update-package

By default, WSL version 1 is the default version. We’ll need the updated WSL2. To set WSL2 as default, type the following in the command prompt:

wsl --set-default-version 2

Get yourself Ubuntu (or other Linux distro)

At the beginning of Docker Desktop on Windows 10 Home, the next step would be to install docker and then use the docker-cli from within Windows. However, a much better performance can be achieved if we host our files on a separate Linux distribution. All mounting issues and network latency issues are solved then! So open your Microsoft Store and search for WSL:

At the time of writing this post, a bunch of distributions is already available for WSL, including Ubuntu, Fedora, Kali, Alpine. The full list can be found here:

https://docs.microsoft.com/pl-pl/windows/wsl/install-win10#step-6—install-your-linux-distribution-of-choice

In this post we’ll be using Ubuntu 20.04 LTS. So get it and install it. It will take a short while to install. Once installed, type in your console:

wsl --list --verbose

That will list the currently installed and available docker distros, including their state (Running or Stopped) and version (1 or 2):

If for some reason you skipped setting default version to 2, and your distribution shows version 1, you can update it with command:

wsl --set-version <YOUR DISTRIBUTION NAME> <VERSION TO CHOOSE 1 OR 2>

wsl --set-version Ubuntu-20.04 2

Get yourself Windows Terminal (optional)

Windows Console (cmd.exe) has always been there but is a bit clumsy to use. PowerShell is a nice improvement, but still not there yet. Microsoft has recently released a new Windows Terminal, which improves the terminal experience a lot with the ability to use tabs and customize the look and feel of the terminal. You can download it from Microsoft Store:

https://www.microsoft.com/en-us/p/windows-terminal/9n0dx20hk701?rtc=1&source=lp&activetab=pivot:overviewtab

There is a few useful shortcuts to use when working with Windows Terminal:

Ctrl + Shift + T opens a new tab
Ctrl + Tab goes to the next tab
Ctrl + Shift + Tab goes to the previous tab
Ctrl + Alt + 1 goes to the first tab, Ctrl + Alt + 2 to the second etc.

Installing Docker Desktop on Windows 10 Home

Now that all the prerequisites are there, let’s install Docker Desktop on Windows 10 Home. You can download the installer from here: https://hub.docker.com/editions/community/docker-ce-desktop-windows/.

When you run the installer, make sure to tick the WSL2 backend:

Once installed (you will have to log out and back in), run the Docker Desktop and once it’s running, right-click its icon in the system icon tray and then click Settings. On the settings tab choose WSL Integration and enable integration for your WSL2 Linux distro:

This will allow to manage the docker with its command line interface (docker-cli) from within Ubuntu-20.04 WSL.

Test your Docker on Windows 10 Home with WSL 2

Now that both the WSL2 and Docker Desktop on Windows 10 Home are installed you’re good to test it. Let’s try running an nginx container. Hop in to your WSL distro and run the command:

docker run -d --name docker-nginx -p 8080:80 nginx

Wait a minute for the nginx container to get pulled and started, and then run the command:

docker ps

You will see your docker instance running on WSL:

Now go to your Windows favorite browser and navigate to http://localhost:8080. You’ll see your dockerized nginx ran from within your WSL distro of choice!

You can now leave the WSL console and the container will keep running. To stop it and free the resources run:

docker stop docker-nginx

docker rm docker-nginx

How to access my WSL distro files from Windows 10 Home?

Using WSL2 + Docker Desktop on Windows 10 Home has a huge benefit over using a traditional virtual machine. It’s the filesystem integration. You can access all files from all your distros on Windows files explorer by navigating with the file explorer to \\wsl$:

This network resource will list all your active WSL distros. You can go inside and it will list your files. This is the preferred way of working with WSL + Docker Desktop on Windows 10 Home, because of the great performance of data access.

Alternatively, you can still use your Windows drives, and access them from WSL:

ls /mnt/c/Users/artur

This does work, but the access is slow, especially for projects with lots of files.

Running real-life project on Docker Desktop on Windows 10 Home the right way

Right, so after all these preliminary actions we are finally ready to run our real-life project on Docker Desktop. Let’s start by creating your SSH keys for GIT. Go to your WSL terminal and run:

ssh-keygen

Accept all defaults by pressing Enter.

This will generate a pair of keys – private and public – for use inter alia with your git account. You can get the public key by calling:

less ~/.ssh/id_rsa.pub

At IdeaSpot we’re using GitLab for our code. To add the SSH key go to your Profile -> SSH Keys and paste your key obtained from the command above. The Title will get filled automatically for you:

Now you’re good to clone your repo. Go to the home directory and clone the project to the directory of your preference:

cd ~

git clone git@my.git.repo:project/repo.git my_project_dir

If there are any warnings about unknown fingerprints, you’re good to accept the keys. The repo clones to your drive:

In order to edit your code, of course we want to use Windows and not WSL Linux distro. Thankfully, we can use the Windows-Linux integration of the WSL2. In PhpStorm (or other IDE of your liking), just navigate to the newly-cloned project on the \\wsl$\ network share:

And that’s it! You’re ready to go!