Docker Engine on WSL2

This tutorial contains instructions to install Docker Engine (not Docker Desktop) on WSL2 distribution. For instance, an Ubuntu 22.04 distribution will be used.

Uninstall any Docker version

Make sure you have fully uninstalled any versions of Docker. The instructions to uninstall can be found here.

Installation, starting and testing

First install the Linux Subsystem with a PowerShell command:

$ Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux

Ensure that you have the latest version of WSL installed. To make this, run:

$ wsl --update

Then install Ubuntu distribution. You should be asked to input an username and password for Linux login.

$ wsl --install Ubuntu-22.04
Installing: Ubuntu 22.04 LTS
Ubuntu 22.04 LTS has been installed.
Launching Ubuntu 22.04 LTS...
Installing, this may take a few minutes...
Please create a default UNIX user account. The username does not need to match your Windows username.
For more information visit: https://aka.ms/wslusers
Enter new UNIX username: <Linux username>
New password:
Retype new password:
passwd: password updated successfully
Installation successful!

After that, you should proceed installing Docker Engine (as described here).

$ curl -fsSL https://get.docker.com | sudo sh

NOTE: On this step you'll receive a recommendation to use Docker Desktop - dismiss it.

Finally, test the Docker (it must show an empty list of containers):

$ sudo docker ps
CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES

Try running the hello-world container.

$ sudo docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
719385e32844: Pull complete
Digest: sha256:fc6cf906cbfa013e80938cdf0bb199fbdbb86d6e3e013783e5a766f50f5dbce0
Status: Downloaded newer image for hello-world:latest

Hello from Docker!
This message shows that your installation appears to be working correctly.

...

To get out of the Ubuntu WSL2 bash, type exit and enter.

Running Docker commands without 'sudo'

To run Docker with Ubuntu username, append docker group to the Ubuntu WSL user:

$ sudo usermod -aG docker $USER

Accessing IMDS (Weep) on Windows (host) from WSL

Preparation

On Ubuntu WSL shell (bash), run:

$ echo "$USER ALL=(ALL) NOPASSWD: /usr/sbin/ip,/usr/sbin/iptables" | sudo tee /etc/sudoers.d/99-allow-iptables

Then:

NOTE: copy all the lines after $ symbol and paste on shell

$ echo "
# Weep workaround
windows_ip=\$(ip route | grep default | cut -d' ' -f3)

if ! sudo iptables -t nat -L OUTPUT | grep \${windows_ip}:9091 > /dev/null; then
  sudo iptables -t nat -L PREROUTING --line-numbers | grep to:.*:9091 | sed 's/\([0-9]*\).*/\1/g' | tac | xargs -I{} sudo iptables -t nat -D PREROUTING {}
  sudo iptables -t nat -I PREROUTING 1 -p tcp --dport 80 -d 169.254.169.254 -j DNAT --to \${windows_ip}:9091

  sudo iptables -t nat -L OUTPUT --line-numbers | grep to:.*:9091 | sed 's/\([0-9]*\).*/\1/g' | tac | xargs -I{} sudo iptables -t nat -D OUTPUT {}
  sudo iptables -t nat -I OUTPUT 1 -p tcp --dport 80 -d 169.254.169.254 -j DNAT --to \${windows_ip}:9091
fi
" | tee -a $HOME/.profile

Running Weep command

To make weep/IMDS reacheable from WSL, you need to bind Weep to WSL virtual network adapter. To bind weep to all the available interfaces, you need to add -a 0.0.0.0 arguments to Weep command. On Windows PowerShell, run:

$ weep serve SWE-012345678901 -a 0.0.0.0

Replace SWE-012345678901 with your AWS profile id.

How To Integrate Docker And Docker Compose Into Your PowerShell

You are able to use all Docker commands inside your Ubuntu submodule and also within a PowerShell by preceding the command with wsl:

$ wsl docker ps

For convenience, you should be able to use any Docker command without adding wsl in front of it. To achieve this you can create an alias for your PowerShell. To edit the PowerShell profile, run:

$ notepad $PROFILE

The append the following content to the file:

Function Start-WslDocker {
    wsl docker $args
}

Set-Alias -Name docker -Value Start-WslDocker

Save the file and restart your PowerShell terminal to test if the alias is working by typing:

$ docker ps

If you don’t get an error it works as expected.

Accessing Ubuntu shell

To manage docker containers and other Linux related configurations you may need to enter into Ubuntu shell. To access Ubuntu shell, run on PowerShell:

$ bash

To leave Ubuntu shell, run:

$ exit

References

How To Install Docker Without Docker Desktop On Windows

ffosilva/README.md