How to migrate from Docker Desktop to Rancher Desktop — the complete guide

with troubleshooting

You might find yourself and your environment (for development) depending on Docker Desktop, which used to be a nice free tool, but now (rightfully) charges money through a subscription for enterprises (and more recently also increased their prices). So if you want to keep every workflow you’re already doing/using intact but get rid of Docker Desktop at the same time, follow this guide.

Photo by Rubaitul Azad on Unsplash

1. Uninstall Docker Desktop (requires Admin)
2. Open PowerShell, run wsl (or wsl -d docker-desktop) and navigate to /var/lib and if there is still a docker folder there, delete it (rm -rf docker) otherwise there will be errors
3. Download and install (requires Admin): Rancher Desktop. It installs in the %APPDATA%, so make sure to install it in the current’s user folder, not in the Administrator one.
4. At first run, you’ll get a pop-up to select the configuration to use. Enable kubernetes (latest stable) only if you use kube, and select dockerd (not containerd) as engine
5. Enable container-host communication by allowing traffic by running this command in PowerShell (requires Admin). From this step forward, no further admin rights are required.
6. Go to settings → WSL → and enable your already installed WSL2 distribution (should be Ubuntu) integration
7. At this step, you theoretically have access to all the docker and kubectl commands
8. The docker desktop wsl volume data might not be deleted after the uninstall and it usually uses a lot of space. You must delete it by running wsl --list -v (and here you will see docker-desktop-data and docker-desktop), and then run wsl --unregister docker-desktop-data and wsl --unregister docker-desktop
9. Now start Rancher Desktop, run your scripts (that depend on thedockercommand), build/start your containers etc. Everything should run smoothly. You must build everything again since containers are not cross-engine (if you had mounted data through bound volumes for specific containers, you’ll still have it)

Troubleshooting

Startup errors

If you get an error at first startup or don’t see a window that prompts you to select the engine OR the version displayed is not 1.6.1+ (or latest displayed on the website), then you have to manually replace the rancher desktop files (no need for admin):

1. Go to %AppData$\Local\Programs\Rancher Desktop
2. Extract and replace here all the contents of the app. The contents of the app can be found by opening the Setup file with 7zip, and navigating to $PLUGINSDIR → app-64.7z.
3. If you ever want to update the application, it will not work from inside the application. But if you follow these manual steps, you’ll have a new version.

Kubernetes port conectivity errors

If you get a Kubernetes error on port connectivity, go to settings and change the port to something else (and restart)

Disk space problems

If you had problems with space on C (where wsl defaults its data), follow these next steps to move your data container to another partition:

1. Open powershell.
2. Close Rancher Desktop. Make sure everything is shut down by running (powershell) wsl --shutdown
3. Open powershell and type wsl --list -v. You should see rancher-desktop-data (similar to docker-desktop-data)
4. Export the data file to the other partition by running this command (and replacing the path with yours): wsl --export rancher-desktop-data D:\\volumes\\rancher-desktop-data.tar.
5. Unregister the existing data file by running esl --unregister rancher-desktop-data.
6. Import the new location for the data by running (and replacing the path with yours): wsl --import rancher-desktop-data D:\\volumes\\ D:\\volumes\\rancher-desktop-data.tar --version 2. Wait a while. Then test with wsl --list -v to see the data appears.
7. Start back Rancher Desktop. You should have all your containers in place but using the new location.

Possible downsides and things to consider

1. Rancher Desktop has built-in commands and container management UI when upping them with docker-compose. On plain containers, it doesn’t have any management UI working (so hard to re-start, stop etc.). But tools like the VSCode Docker Extension — which is fast — , DockerStation — which offers a nice UI but is a bit slow — or Lazy Docker — a console-like UI — can do the task.
2. Any applications that were dependent on Docker Desktop specifics (e.g. using the exposed TCP daemon or specific non-standard commands) will stop working and will need workarounds (like creating new containers to expose the port)
3. For logs, either use docker logs -f <container-name>, the UI tool from point (a) or install ELK in your system and see all the logs in Kibana (kibana should be the preferred option)
4. host.docker.internal, if you’re using it, might still work. But if it doesn’t (especially on Windows), you will need alternatives. For example, if running an nginx server to bind together one app running locally and one running as a container (e.g. to debug a web application in VSCode), you will need to download nginx into a folder from here (make sure to download the same version you’re using containerized) and update your nginx.conf file to do all the proxying to [localhost](<http://localhost>) (since it’s running on localhost)
5. To restart all containers either use the UI tool from point (1) or from powershell/bash: docker restart $(docker ps -a -q)