DEV Community

Cover image for Replace Docker with Rancher Desktop and WSL2 on Windows
Nathan Crum
Nathan Crum

Posted on • Updated on

Replace Docker with Rancher Desktop and WSL2 on Windows

Updated to include instructions for insecure registry.

How far we've come

Prior to version 1.0 of Rancher Desktop it was an interesting alternative to Docker Desktop in Windows and in many cases it may have been all many users needed. Working in a larger company with private on premises registries, custom Certificate Authorities, and heavy Visual Studio use with their Docker integration proved unable to work.

Now that 1.0 has released I decided to give it another try. I am thoroughly impressed with the progress this team has made and the strides they have taken to make it as accessible to as many people and the way they work as possible. Today I'm going to show you how easily you can replace docker desktop and work with a private registry protected by a Custom CA or an insecure registry you might be using if you are experimenting with hosting your own images.

Using dockerd as the runtime

Rancher Desktop has plenty of info on installing the tool so refer the the link for those instructions and I will get right into configuration.

While you can have Docker Desktop and Rancher Desktop installed on the same machine, make sure that you completely close the Docker Desktop application before running Rancher Desktop as they both will want to use the same socket.

Let's get started! Open Rancher Desktop and navigate to the "Kubernetes Settings" tab then select "dockerd(moby)" as the container runtime. If you selected this during installation you can skip to Working with a custom CA or Using an insecure registry depending on your use case. You will be warned that this will cause Kubernetes to restart. Accept this and continue.

Moby container runtime toggle

If you have already built images with containerd and nerdctl these get stored in a way that dockerd cannot access and you will need to build those again later.

After some time Kubernetes will finish restarting and you can start using the same docker cli commands you have always used. Because dockerd is also using the same sockets for the daemon as Docker Desktop your same docker extensions for VS Code and Visual Studio will work just as they had before.

Working with a custom CA

If you need to work with a container registry that is using a Custom CA then you will run into an error like below if you try to push or pull using it. This is because docker daemon now lives in the rancher-desktop wsl instance which does not inherently trust the same CA's your laptop may have installed.

x509 error

In order to correct this you must copy your root and intermediary CA certs to \\wsl$\rancher-desktop\usr\local\share\ca-certificates. This can be pasted in Windows Explorer to easily navigate to the folder.

Custom Certs Pasted into WSL cert path

After the certs have been copied over open your terminal and connect to the rancher-desktop shell. Then run the command update-ca-certificates as shown below.

> wsl -d rancher-desktop -e /bin/sh

# Updates the certificates to include your custom ones
# in /etc/ssl/certs
/mnt/c/Users/{user} > update-ca-certificates
Enter fullscreen mode Exit fullscreen mode

After you have updated the certs verify that they show in /etc/ssl/certs. It will rename them to something like ca-cert-{filename.ext}.pem

Now quit and restart the Rancher Desktop application in windows. When it has completed starting up again you should now be able to successfully connect and work with your private registry.

Successful docker pull from private registry

Using an insecure registry

If you have setup a basic registry for storing your images on premises and you don't have a trusted CA cert for SSL, then you might encounter an error similar to below.

...http: server gave HTTP response to HTTPS client
Enter fullscreen mode Exit fullscreen mode

To trust the registry we first need to create a file at /etc/docker/daemon.json on the WSL2 instance where the daemon is running

> wsl -d rancher-desktop -e vi /etc/docker/daemon.json
Enter fullscreen mode Exit fullscreen mode

Paste in the following being sure to edit the registry:port to match the one you are using:

  "insecure-registries" : [ "" ]

Enter fullscreen mode Exit fullscreen mode

Then create a file at /etc/default/docker:

> wsl -d rancher-desktop -e vi /etc/default/docker
Enter fullscreen mode Exit fullscreen mode

And paste this as the contents:

Enter fullscreen mode Exit fullscreen mode

Now quit and restart rancher desktop and push/pull and image for the insecure registry again to confirm it is working.

Top comments (1)

shawn1874 profile image
Shawn Fox

Why is it necessary to run vi in that manner instead of directly? Is there some reason I can't simply create the file directly? Also do these instructions actually work on Windows as the article suggests? The directory being modified implies more of a Linux desktop solution.