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.
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.
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.
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
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.
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
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
Paste in the following being sure to edit the registry:port to match the one you are using:
{
"insecure-registries" : [ "192.168.1.100:5000" ]
}
Then create a file at /etc/default/docker:
> wsl -d rancher-desktop -e vi /etc/default/docker
And paste this as the contents:
DOCKER_OPTS="--config-file=/etc/docker/daemon.json"
Now quit and restart rancher desktop and push/pull and image for the insecure registry again to confirm it is working.
Top comments (2)
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.
Sorry I didn't notice any comments. Rancher desktop runs inside of Windows Sub-System for linux and the file that needed to be edited was in this Sub OS of Windows so we were using the wsl cli to execute the vi command inside of the Rancher Desktop distro "-d"
This article is very dated now and none of it is necessary with the newer versions of Rancher Desktop