Web development environment with WSL 2 and Docker.

With Windows 10 2004 update come a new version of the Windows Subsystem for Linux aka WSL. I like to work with Linux, and Docker for Web development. However, I’m not a great fan of Docker with Windows, but with WSL 2, it’s suppose to work great. At least, greater than with WSL 1. So, how to enable a Web development environment with Docker using WSL 2 ? Let’s give it a try !

Prerequisite

On your computer, you must enable Virtualization in the BIOS. Depending on your motherboard, on startup, press F2 or DEL and find in the menu, the option of enabling Virtualization.

You must have a Windows 10 Home or Pro edition, version 2004 or higher to enable WSL2.

WSL 2 installation

Before we start installing WSL, I strongly recommend to install first the new Windows Terminal.

Go to the Microsoft Store and look for “Windows Terminal”

It’s more pleasant to use than the Command Prompt.

Step 1, we have to enable the WSL option in Windows.

In the search bar, look for “feature” and click “ “Turn Windows features on or off”

Select “Virtual Machine Platform” & “Windows Subsystem for Linux”

And click “OK”. Windows will now install “WSL”. Once done, you will be prompt to restart Windows.

Now, in a terminal, if you enter :

wsl -l

Windows tell you there is no installed distributions. WSL is working !

At this step, you have WSL 1 installed, not WSL 2. To install WSL 2, you need to download and install the WSL 2 Linux Kernel. Go to this page :

Like always when you install a programm, click “next”, “yes” … until the installation is down.

Once down, you can specify ton run every new distribution with WSL 2 by default (there is no point to use WSL1 anymore)

wsl --set-default-version 2

Sometime, you will see this message :

You have to enable the virtualization option in your BIOS and / or go to “Turn Windows features on or off” and turn on “Virtual Machine Platform”

So, now, we have to install a Linux Distribution !

Step 2, Go to Microsoft Store :

If you search for “Linux”, it will give you all the Linux distribution available for WSL 2.

Choose a distribution and click “Install” . For me, I choose Debian.

When the distribution is installed, click on “Launch” .

You have to choose an username and a password for your debian’s session.

Once done, you have a fully operationnal Debian.

Go back to your terminal, into your PowerShell session, enter :

wsl -l -v

It will prompt all the distribution installed and with which version of WSL :

My default distribution is Debian, and the WSL version used is WSL 1 not WSL 2. Normally, every new distribution is enable to work with WSL 2 by default because we defined it previously, but I want to show you how to choose a specific version of WSL for your distribution.

So to enable Debian with WSL 2, I can use the command bellow :

wsl --set-version <distributionName> <versionNumber>

So, in my case :

wsl --set-version Debian 2

And again :

wsl -l -v

And voilà !

Now, in your terminal, you can select your linux distribution :

And start using it

Note : you can set your Linux terminal by default in the Window Terminal settings. By default, it open a PowerShell terminal, but if you replace the PowerShell GUID by the Linux Distribution GUID, it will start by defaut with the Linux terminal :

Go to Settings ( or Ctrl+, )

In the JSON settings, replace “defaultProfile” by the GUID you want to use by default

In my case, I want to use my Debian terminal, so I copy the GUID value

And paste it as the “defaultProfile”

Now, every new terminal will open a debian terminal by default.

Docker installation

In Windows, go to https://hub.docker.com/editions/community/docker-ce-desktop-windows/ and install Docker Desktop for Windows.

Go to the Docker’s settings and check if “Use the WSL 2 based engine…” option is checked

If you have only one linux distribution installed with WSL 2, this distribution is set as distribution by default. But I you have multiple distribution with WSL 2, you may want to specify one by default.

So to do that, in a PowerShell terminal :

wsl --set-default <distroName>

An to check which distro is your distro by default :

wsl -l -v

The little star mean that Debian is my default distro.

By default, Docker is integrated with the default distribution

Now, we have to install Docker inside the linux distribution. Go to https://docs.docker.com/engine/install/debian/ for a Debian installation

In a linux terminal :

sudo apt-get update -y && sudo apt-get install -y apt-transport-https ca-certificates curl gnupg-agent software-properties-common

Now, add Docker’s official GPG key :

curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -

Add the repository (x86_64/amd64 based)

sudo add-apt-repository \
   "deb [arch=amd64] https://download.docker.com/linux/debian \
   $(lsb_release -cs) \
   stable"

Install Docker Engine :

sudo apt-get update -y && sudo apt-get install -y docker-ce docker-ce-cli containerd.io

And add your user to the Docker’s group :

sudo usermod -a -G docker $USER

And check if docker is running :

docker -v

Docker-compose installation

To work with Docker, you create container with a command line, but a command line is not easy to handle when you want to restart often your environment like you can do in a web environment.

Docker-compose is like a recipe for Docker and it’s more friendly to use than command line. For Web development, I like to have a Docker-compose for each project I work. It’s easy to start, restart and update and each environment is independant.

You can download and install Docker-compose like this :

sudo curl -L "https://github.com/docker/compose/releases/download/1.26.0/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose

And make sure Docker-compose is executable :

sudo chmod +x /usr/local/bin/docker-compose

You can check if Docker-compose is working :

docker-compose -v

Everything is working ! Now you can work with Docker on WSl 2 !

VSCode Installation

Now, I need a text editor if I want to make some code. VS Code work great with WSL 2. It has an extension Remote WSL that allows you to access and open yours files from WSL in Windows.

Install VSCode : https://code.visualstudio.com/

Inside a Linux terminal, enter :

code .

It will open VScode inside Windows and propose to you to install “Remote — WSL”

Click “Install” .

Close and reopen both VSCode an the linux terminal. In the Linux terminal, you need to install “wget”.

sudo apt install wget

Now, reopen VSCode :

code .

Now you will see at the bottom left “WSL: Debian” It’s mean that VSCode is now connected to my Debian session.

If you open a terminal inside VScode, it will be in a linux session :

Additionnal tool

Now that VScode is working with WSL 2 and Docker, we can install some others tools like Nodejs

To install NodeJS :

curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
sudo apt-get install -y nodejs

It’s working, now, I have Nodejs and NPM installed.

Test if everything is working with a new Symfony’s project

I have WSL 2, Docker and Vscode ready to go. Now it’s time to see if everything is working good with a new project. I often work with Symfony for PHP‘s projects, so I will test if I can make a new Symfony project.

First, I need to install PHP and Composer to initiate the Symfony project

sudo apt install php php-xml php-zip unzip

php-xml and php-zip are requiert to install Symfony, unzip is recommended by Composer.

And I can use this script to install Composer

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php -r "if (hash_file('sha384', 'composer-setup.php') === 'e0012edf3e80b6978849f5eff0d4b4e4c79ff1609dd1e613307e16318854d24ae64f26d17af3ef0bf7cfb710ca74755a') { echo 'Installer verified'; } else { echo 'Installer corrupt'; unlink('composer-setup.php'); } echo PHP_EOL;"
php composer-setup.php
php -r "unlink('composer-setup.php');"

I like to have Composer enable globally so I use this command

mv composer.phar /usr/local/bin/composer

Composer is working globally

I can make a new Symfony project, so with a linux terminal, inside the folder where you want to have your project, enter :

composer create-project symfony/skeleton projectName

Go to your project folder

cd projectName

Now I have a Symfony project. I need a docker environment with Nginx, PHP and MariaDB to run it.

I made my own docker setup : https://github.com/fred-lab/Docker_Symfony so I will use it to run this Symfony project.

I copy the content of the github project inside the Symfony folder and merge the content of .env and .env.dist in the same file (.env) DON’T DO THAT IN PROD ! since .env is now commited by default by Symfony.

Now I can test if my docker-compose is working

docker-compose config

If no error, it’s time to build each container :

docker-compose up -d

Check if my containers are up :

docker-compose ps

Now, I can go to Chrome : http://localhost:80 and I have my Symfony project running

With WSL 1, inside a Docker container, I did have permissions issues, the container didn’t inherit of the permissions of the WSL instance : everything inside the container was own by Root, even if in the WSL instance, everything was own by my user. It’s was a pain in the ass, because I couldn’t even clear the cache or install apackages with composer, I have permissions issues all the time.

With WSL, it’s seems working great, without permissions issues, I have the same permissions inside the container that my WSL 2 session

That’s all ! I can now working with Docker for Symfony project on Windows with WSL 2.
I prefer to work on linux because it is more customizable and it is “native”, but WSL 2 is a good option especially if I want to do a little design with applications that does not work on Linux like Adobe XD.

I hope you enjoy this little guide. See you !