DEV Community

Felipe Santos
Felipe Santos

Posted on • Edited on

Running Docker on WSL2 without Docker Desktop (the right way)

#docker #linux #windows #wsl

So, now that Docker Desktop is paid under certain scenarios, you may want to switch to something else.

This is a straight to the point guide on how to make Docker CE run fully on WSL2.

PS: the title says right way, but it is just my personal opinion. I am not claiming that any other guide does it in a wrong way.

What you will get

  • A full-fledged Docker installation on WSL2
  • Docker Daemon automatic start without any crazy hacks

What you will not get

  • Docker Daemon sharing between Windows and WSL (i.e. you cannot run docker from Windows PowerShell)
  • Docker Daemon sharing between WSL distributions

Requisites

I will consider that you already have WSL2 working, and you are using Ubuntu as your distribution.

Guide

  1. Install Docker CE on Ubuntu by following the official guide: 
   # Ensures not older packages are installed
   $ sudo apt-get remove docker docker-engine docker.io containerd runc

   # Ensure pre-requisites are installed
   $ sudo apt-get update
   $ sudo apt-get install \
       ca-certificates \
       curl \
       gnupg \
       lsb-release

   # Adds docker apt key
   $ sudo mkdir -p /etc/apt/keyrings
   $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

   # Adds docker apt repository
   $ echo \
       "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
       $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

   # Refreshes apt repos
   $ sudo apt-get update

   # Installs Docker CE
   $ sudo apt-get install docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
Enter fullscreen mode Exit fullscreen mode
  1. Perform the post-installation steps: 
   # Ensures docker group exists
   $ sudo groupadd docker

   # Ensures you are part of it
   $ sudo usermod -aG docker $USER

   # Now, close your shell and open another for taking the group changes into account
Enter fullscreen mode Exit fullscreen mode
  1. Make Docker Daemon start on WSL initialization:

First, make sure you are running a recent version of WSL2 (you can update with wsl.exe --update).

Then, you only need to add:

   [boot]
   systemd=true
Enter fullscreen mode Exit fullscreen mode

To your /etc/wsl.conf within your WSL distribution.

Then, restart it with wsl.exe --shutdown.

To verify that docker works, you can run docker version. If you do not receive any permission denied error, you are good to go.

You can also verify that Docker Compose got installed by running docker compose version.

Bonus

  1. Installing Docker Compose Switch (to use the legacy docker-compose command instead of docker compose): 
   # Finds the latest version
   $ switch_version=$(curl -fsSL -o /dev/null -w "%{url_effective}" https://github.com/docker/compose-switch/releases/latest | xargs basename)

   # Downloads the binary
   $ sudo curl -fL -o /usr/local/bin/docker-compose \
       "https://github.com/docker/compose-switch/releases/download/${switch_version}/docker-compose-linux-$(dpkg --print-architecture)"

   # Assigns execution permission to it
   $ sudo chmod +x /usr/local/bin/docker-compose
Enter fullscreen mode Exit fullscreen mode

PS: I suggest to install the docker-compose binary to /usr/local/bin/ because otherwise, the VS Code - Dev Containers extension will not find it.

To verify it works, you can run docker-compose version.

  1. Install the Docker Credential Helper:

You will need this if you want Docker to store your credentials securely when you perform docker login. Thanks to the WSL interoperability between Windows, you can install the Windows version of the Docker Credential Helper inside of WSL itself.

   # Finds the latest version
   $ wincred_version=$(curl -fsSL -o /dev/null -w "%{url_effective}" https://github.com/docker/docker-credential-helpers/releases/latest | xargs basename)

   # Downloads and extracts the .exe
   $ sudo curl -fL -o /usr/local/bin/docker-credential-wincred.exe \
       "https://github.com/docker/docker-credential-helpers/releases/download/${wincred_version}/docker-credential-wincred-${wincred_version}.windows-$(dpkg --print-architecture).exe"

   # Assigns execution permission to it
   $ sudo chmod +x /usr/local/bin/docker-credential-wincred.exe
Enter fullscreen mode Exit fullscreen mode

Then, configure your Docker CLI to use it by assuring that the following is present in your ~/.docker/config.json:

   {
     "credsStore": "wincred.exe"
   }
Enter fullscreen mode Exit fullscreen mode

To verify that it works, you can try to docker login and if not, Docker will complain about storing credentials in plain text.

Final considerations

The entire setup process may take some time, but you will have achieved almost everything that Docker Desktop used to provide to you (by the way, I use k3d as an alternative to Docker Desktop's built-in K8s provisioner).

However, you can achieve a similar (and even higher/better) level of easiness that Docker Desktop provided to you by wrapping all the steps above in your dotfiles installation steps.

For example, in my dotfiles, all these steps are automated, including configuring /etc/docker/daemon.json, changing ~/.profile, and even providing a way to automatically update your extra binaries (docker-compose, or the wincred.exe) every time you update your dotfiles (by using a feature of chezmoi - a dotfiles manager which I totally recommend).

Latest comments (39)

Collapse
 
vikas_bhandari_2e2a7aead1 profile image
Vikas Bhandari •

Docker not starting in wsl2 arm machine. Getting Iptables related issues.
ERROR:

Unable to detect if iptables supports xlock: 'iptables --wait -L -n ': 'iptables v1.8.7 (legacy): can't initialize iptables table 'filter': Table does not exist (do you need to insmod?)

I have tried the switching from iptables-nft to iptables-legacy as well but still seeing the same issue can someone help please.

Collapse
 
bwdavis profile image
bwdavis •

Very good guide, thank you very much. It solved our issue.

Collapse
 
proscatinatingpro profile image
Trung Ly •

Note that if wsl2 is set to networkingMode=mirrored, you will might run into issues trying to connect to the container from your Windows host (on the same local machine). Connecting from other host within the network worked but ymmv depending on your setup. A workaround from on gist.github.com/shigenobuokamoto/b... and github.com/microsoft/WSL/issues/10... finally addressed the issue for me.

Create a new file as root /etc/systemd/system/network-mirrored.service

[Unit]
Wants=network-pre.target
Before=network-pre.target shutdown.target

[Service]
User=root
ExecStart=/bin/sh -ec '\
  [ -x /usr/bin/wslinfo ] && [ "$(/usr/bin/wslinfo --networking-mode)" = "mirrored" ] || exit 0;\
  echo "\
  add chain   ip nat WSLPREROUTING { type nat hook prerouting priority dstnat - 1; policy accept; };\
  insert rule ip nat WSLPREROUTING iif loopback0  ip daddr 127.0.0.1 counter dnat to 127.0.0.1 comment mirrored;\
  "|nft -f -\
'
ExecStop=/bin/sh -ec '\
  [ -x /usr/bin/wslinfo ] && [ "$(/usr/bin/wslinfo --networking-mode)" = "mirrored" ] || exit 0;\
  for chain in "ip nat WSLPREROUTING";\
  do\
    handle=$(nft -a list chain $chain | sed -En "s/^.*comment \\"mirrored\\" # handle ([0-9]+)$/\\1/p");\
    for n in $handle; do echo "delete rule $chain handle $n"; done;\
  done|nft -f -\
'
RemainAfterExit=yes
[Install]
WantedBy=multi-user.target
Enter fullscreen mode Exit fullscreen mode

When you have created the file, run it by $ sudo systemctl --now enable network-mirrored. This may or may not resolve the issue. If it doesn't, add the following to your ** .wslconfig**, the one found in **Windows **host, not the Linux distro (wsl.config).

firewall=false
dnsTunneling=true
Enter fullscreen mode Exit fullscreen mode

So that your full file could look something like this:

[wsl2]
networkingMode=mirrored
firewall=false
dnsTunneling=true

[experimental]
autoMemoryReclaim=gradual
Enter fullscreen mode Exit fullscreen mode

Reboot your wsl2 instance from powershell and open a new wsl2 instance:

wsl --shutdown
wsl
Enter fullscreen mode Exit fullscreen mode
Collapse
 
abirb profile image
abirax • • Edited

Hi Felipe,

Thanks for the article, I am on ubuntu 22 I am able to start docker but unable to pull images from docker.io I get an error
When I run docker pull hello-world
i get the error:
Using default tag: latest
Error response from daemon: unknown:

408 Request Time-out


Your browser didn't send a complete request in time.

any idea? My proxies are fine since I can run curl docker.io -v
I also tried docker login and it didnt work
I get errors like
docker: Error response from daemon: Get "registry-1.docker.io/v2/": dial tcp: lookup registry-1.docker.io on [::1]:53: read udp [::1]:56718->[::1]:53: read: connection refused.

Collapse
 
bhabermann profile image
Bruno Habermann •

Excelente conteúdo! Me ajudou demais.

Collapse
 
sstranks profile image
Simon Stranks •

Any idea how to get rootless working on WSL2? I can get the rootless daemon running successfully, but it won't connect to the docker registry when trying to pull images - 'no such host'.

I managed to get it working on WSL2 Ubuntu 20.04 then stupidly upgraded it (and WSL2). Something somewhere obviously broke and now I can't get it working again.

Collapse
 
sstranks profile image
Simon Stranks •

OK just found the solution: github.com/microsoft/WSL/issues/74...

I'm using WSL2 on Windows 10, Ubuntu 22.04 LTS.

  • Install Docker Engine using the official instructions, using apt-repository method docs.docker.com
  • Install Docker Rootless using the official instructions docs.docker.com - add the '--skip-iptables' flag to the install command.
  • As per the solution linked above, create/amend the '/etc/wsl.conf' file to enable 'systemd' (works on WSL2 now, both Windows 10 and 11) and disable WSL from automatically creating '/etc/resolv.conf', so we can create our own manually and set the nameserver to 1.1.1.1.

You don't need to change iptables to legacy anymore either, you can leave them on the newer nft setting.

Collapse
 
ac76 profile image
Adam Carr • • Edited

You can run the commands in Powershell. You need to add proxy functions to your $PROFILE.

Replace the {} tokens with the relevant distribution and the username you use in that distribution.

function docker {
    wsl -d "{DISTRO_NAME}" -u {DISTRO_USER} -e docker $args
}

function docker-compose {
    wsl -d "{DISTRO_NAME}" -u {DISTRO_USER} -e docker-compose $args
}
Enter fullscreen mode Exit fullscreen mode
Collapse
 
felipecrs profile image
Felipe Santos •

Thanks for the tip, I would also recommend using PowerShell-WSL-Interop to achieve this.

Collapse
 
mhangaard profile image
Martin Hangaard Hansen •

Thank you for this tutorial @felipecrs . Will this work together with an Azure Client installed on windows?

For example:
$ which az
/mnt/c/Program Files (x86)/Microsoft SDKs/Azure/CLI2/wbin/az

with az acr login?

Thanks
Martin

Collapse
 
felipecrs profile image
Felipe Santos •

If it delegates to the docker cli I see no reason for it not to work. Let me know if you ended up testing it, though.

Collapse
 
mhangaard profile image
Martin Hangaard Hansen •

I couldn't get it to do it, but worked around by taking the token from az and passing it to docker login

docker login ${MY_ACR}.azurecr.io -u 00000000-0000-0000-0000-000000000000 -p $(az acr login -n ${MY_ACR} --expose-token | jq .'accessToken' | tr -d \")
Enter fullscreen mode Exit fullscreen mode
Collapse
 
douglewis22 profile image
douglewis22 • • Edited

Felipe,

First let me say thank you for sharing this with us! It is a very good help.

I do have one small issue. Today when I attempted to get the credential helper setup I get the following error:

curl: (22) The requested URL returned error: 404

I can see the .exe file for v0.7.0 but not seeing a .zip file though. So, I downloaded the .exe file and copied it to the /usr/local/bin location, issued the chmod command and tried the docker login and it was successful.

Collapse
 
felipecrs profile image
Felipe Santos •

Hey, thanks for reporting it.

You're right about copying the file to /usr/local/bin, but don't forget to give it execution permission as well.

I updated the guide to point the new changes.

Collapse
 
david24622147 profile image
David •

This is an excellent replacement except I haven't been able to get K8s clusters from the WSL side to connect on the devcontainer side. Docker Desktop offers its built-in cluster API at a special address that resolves correctly back out of the devcontainer. Any other cluster: kind, k3d, minikube, created on the WSL side will not resolve inside the devcontainer.

This is the devcontainer feature I'm using to enable cluster access on the devcontainer side using its kubeconfig copy script to copy my local kubeconfig in.

Have you tried this? Is Docker Desktop somehow blessed in its operation?

Collapse
 
felipecrs profile image
Felipe Santos •

In all my devcontainers, I add --network=host to the runArgs of it, so that it does not suffer of this issue.

However, have you tried Rancher Desktop? It may work for you.

View full discussion (39 comments)