Rancher Desktop Setup

Rancher Desktop is a free, open-source container runtime for Windows, macOS, and Linux. It is an alternative to Docker Desktop that provides the same core functionality needed to run Precision Bridge.

When to Choose Rancher Desktop

Docker Desktop requires a paid subscription for commercial use in organisations with more than 250 employees or more than $10 million in annual revenue. Rancher Desktop is licensed under the Apache 2.0 license and is free for all users, including commercial use, with no restrictions based on company size or revenue.

If your organisation falls under Docker Desktop's paid licensing requirements and prefers an open-source alternative, Rancher Desktop is a fully supported option for running Precision Bridge.

Download

Download Rancher Desktop from the official website:

Download Rancher Desktop

Select the appropriate installer for your operating system.

Installation — Windows

Run the downloaded installer
Follow the on-screen prompts to complete the installation
Rancher Desktop will launch automatically after installation, or you can open it from the Start menu

Prerequisite: WSL 2 must be enabled on Windows. If it is not already installed, open PowerShell as Administrator and run wsl --install, then restart your computer. See Microsoft's WSL installation guide for details.

Installation — macOS

Open the downloaded .dmg file
Drag the Rancher Desktop icon into the Applications folder
Open Rancher Desktop from your Applications folder or Launchpad
macOS may ask you to confirm opening an application downloaded from the internet — click Open

Critical Configuration: Selecting dockerd (moby)

This is the most important step. Precision Bridge will not work unless the correct container runtime is selected.

By default, Rancher Desktop uses the containerd runtime. This runtime does not provide the standard docker and docker compose CLI commands that Precision Bridge requires. You must switch to the dockerd (moby) runtime.

Steps

Open Rancher Desktop
Navigate to Preferences (gear icon) > Container Engine
Select dockerd (moby) as the container runtime
Click Apply — Rancher Desktop will restart its backend to apply the change

Why This Matters

Precision Bridge's installer and Docker Compose files rely on the docker and docker compose commands. The dockerd (moby) runtime provides these commands because it runs the same Docker engine that Docker Desktop uses. The containerd runtime uses a different toolchain (nerdctl) and does not expose these commands.

What Happens If You Use containerd

If the runtime is set to containerd, you will encounter errors such as:

docker: command not found
docker compose: command not found
Precision Bridge installer fails to detect Docker
Precision Bridge containers fail to start

If you see any of these errors, check your Rancher Desktop container runtime setting and switch to dockerd (moby).

Disabling Kubernetes

Rancher Desktop includes a built-in Kubernetes cluster that is enabled by default. Precision Bridge does not use Kubernetes, so you can safely disable it to save system resources (approximately 1-2 GB of RAM).

Open Rancher Desktop
Navigate to Preferences > Kubernetes
Uncheck Enable Kubernetes
Click Apply

This is optional but recommended, especially on machines with limited memory.

Resource Allocation

Like Docker Desktop, Rancher Desktop allocates system resources for running containers. For Precision Bridge, we recommend at least:

Memory: 4 GB (8 GB recommended for larger projects)
CPUs: 2 cores

To adjust these settings:

Open Rancher Desktop
Navigate to Preferences > Virtual Machine (or Resources, depending on your version)
Adjust the memory and CPU sliders
Click Apply

The Docker Socket Conflict

Docker Desktop and Rancher Desktop cannot run simultaneously. Both applications manage the Docker socket, which is the communication channel between the docker CLI and the container runtime:

Linux / macOS: /var/run/docker.sock
Windows: A named pipe

If both applications are running at the same time, you will experience unpredictable behaviour — commands may fail, containers may not start, or one runtime may interfere with the other.

How to Avoid Conflicts

Before starting Rancher Desktop, ensure Docker Desktop is fully stopped:

Right-click the Docker Desktop icon in the system tray (Windows) or menu bar (macOS)
Select Quit Docker Desktop
Wait a few seconds for it to fully shut down
Then start Rancher Desktop

The same applies in reverse — fully quit Rancher Desktop before starting Docker Desktop.

host.docker.internal Limitation

Rancher Desktop does not always resolve the special hostname host.docker.internal correctly. This hostname is used by containers to communicate with services running on the host machine.

No manual action is needed. Precision Bridge automatically detects when it is running under Rancher Desktop and applies the necessary corrections at startup. This is handled transparently — you do not need to configure anything.

Verifying the Installation

After selecting the dockerd (moby) runtime, open a terminal (Command Prompt, PowerShell, or Terminal on macOS) and run:

docker --version

You should see output similar to:

Docker version 27.x.x, build xxxxxxx

Also verify that Docker Compose is available:

docker compose version

You should see output similar to:

Docker Compose version v2.x.x

These are the same commands and expected output as Docker Desktop, because the dockerd (moby) runtime provides the same Docker CLI.

If docker is not recognised as a command, verify that:

Rancher Desktop is running
The container runtime is set to dockerd (moby) (not containerd)
Your terminal was opened after Rancher Desktop finished starting (close and reopen the terminal if needed)

Troubleshooting

Wrong Runtime Selected (Most Common Issue)

Symptom: docker: command not found or docker compose: command not found despite Rancher Desktop running.

Solution: Open Rancher Desktop, go to Preferences > Container Engine, and switch to dockerd (moby). Restart Rancher Desktop and reopen your terminal.

Socket Conflicts with Docker Desktop

Symptom: docker commands return unexpected errors, containers from the wrong runtime appear, or Precision Bridge fails to start.

Solution: Ensure only one container runtime is running at a time. Fully quit Docker Desktop before using Rancher Desktop (and vice versa). After stopping the other runtime, restart Rancher Desktop to re-establish its socket connection.

Cannot Connect to Docker Daemon

Symptom: Cannot connect to the Docker daemon. Is the docker daemon running?

Solution: 1. Ensure Rancher Desktop is open and fully started (check for the icon in your system tray or menu bar) 2. Confirm the runtime is set to dockerd (moby) 3. Try restarting Rancher Desktop via File > Restart or by quitting and reopening the application

Networking Issues

Symptom: Containers cannot reach external services, or Precision Bridge cannot connect to target systems.

Solution: - Ensure your firewall or VPN is not blocking Docker's network traffic - Try restarting Rancher Desktop - If using a corporate VPN, you may need to configure Rancher Desktop's network settings or consult your IT department - On Windows, ensure WSL 2 networking is functioning correctly — run wsl --shutdown in PowerShell, then reopen Rancher Desktop

Rancher Desktop Fails to Start

Symptom: Application crashes on launch or hangs during initialisation.

Solution: 1. On Windows, ensure WSL 2 is up to date: run wsl --update in an elevated PowerShell 2. Try performing a factory reset: open Rancher Desktop, go to Troubleshooting > Factory Reset 3. If the application will not open at all, uninstall and reinstall from rancherdesktop.io

Next Steps

Rancher Desktop is installed and running. Proceed to Download and Install to install Precision Bridge.