Skip to main content

Docker Desktop Setup

James Herring
Updated

Docker Desktop Setup

Precision Bridge runs as a set of Docker containers — lightweight, isolated environments that package the application and all its dependencies together. This means you don't need to install Python, Node.js, databases, or any other software directly on your machine. Everything runs inside containers.

To manage these containers, you need a container runtime installed on your system. Docker Desktop is the most widely used container runtime for Windows and macOS, and is the recommended option for most Precision Bridge users.

System Prerequisites

Windows

  • Windows 10 version 1903 or later, or Windows 11
  • WSL 2 (Windows Subsystem for Linux 2) — this is the recommended backend and is required for most configurations. If WSL 2 is not already enabled, Docker Desktop will prompt you to install it during setup.
  • Alternatively, Hyper-V can be used as the virtualisation backend on Windows Pro/Enterprise/Education editions, though WSL 2 is preferred for better performance.
  • Hardware virtualisation must be enabled in your BIOS/UEFI settings (usually labelled "Intel VT-x" or "AMD-V").

macOS

  • macOS 12 (Monterey) or later
  • Supported on both Apple Silicon (M1, M2, M3, M4) and Intel Macs
  • At least 4 GB of RAM available for Docker

Download

Download Docker Desktop from the official website:

Download Docker Desktop

Select the appropriate installer for your operating system (Windows or macOS). For macOS, choose the correct chip architecture (Apple Silicon or Intel).

Installation — Windows

  1. Run the downloaded installer (Docker Desktop Installer.exe)
  2. When prompted, ensure the Use WSL 2 instead of Hyper-V option is selected (recommended)
  3. Accept the license agreement
  4. Follow the remaining on-screen prompts to complete the installation
  5. When installation finishes, you may be prompted to restart your computer — do so if asked
  6. After restarting, Docker Desktop will launch automatically. If it does not, open it from the Start menu.

If WSL 2 is not installed, the Docker Desktop installer guides you through enabling it. You may need to run wsl --install in an elevated PowerShell terminal and restart your computer. See Microsoft's WSL installation guide for detailed instructions.

Installation — macOS

  1. Open the downloaded .dmg file
  2. Drag the Docker icon into the Applications folder
  3. Open Docker Desktop from your Applications folder or Launchpad
  4. When prompted, accept the license agreement
  5. macOS may ask for your password to install networking components — enter it to continue
  6. Docker Desktop will start and appear in your menu bar

First-Run Configuration

When Docker Desktop starts for the first time, it will initialise the Docker engine. This may take a minute or two.

Resource Allocation

Docker Desktop allocates a portion of your system's resources to run containers. For Precision Bridge, we recommend at least:

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

To adjust these settings:

  1. Open Docker Desktop
  2. Click the gear icon (Settings) in the top-right corner
  3. Navigate to Resources > Advanced
  4. Adjust the memory, CPU, and disk sliders as needed
  5. Click Apply & Restart

Note: On Windows with the WSL 2 backend, resource management is handled by WSL 2 and these sliders may not be available. Instead, you can configure WSL 2 memory limits via a .wslconfig file in your user home directory. See Microsoft's WSL configuration documentation for details.

Verifying the Installation

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

If both commands return version information, Docker Desktop is installed and working correctly.

Understanding the Docker Daemon

Docker Desktop runs a background service called the Docker daemon (dockerd). This daemon is responsible for building, running, and managing containers. It must be running before you can start Precision Bridge.

When Docker Desktop is running, you will see the Docker whale icon in your system tray (Windows) or menu bar (macOS). If the icon is present, the daemon is active and ready.

Starting and Stopping Docker Desktop

  • Starting: Open Docker Desktop from the Start menu (Windows) or Applications folder (macOS). The daemon starts automatically when the application opens.
  • Stopping: Right-click the Docker whale icon in the system tray or menu bar and select Quit Docker Desktop. This stops all running containers and shuts down the daemon.

Tip: You do not need to stop Docker Desktop after closing Precision Bridge. It uses minimal resources when idle. However, if you want to free up memory, quitting Docker Desktop will reclaim the resources it had allocated.

Troubleshooting

WSL 2 Not Enabled (Windows)

Symptom: Docker Desktop fails to start or displays an error about WSL 2 not being available.

Solution: 1. Open PowerShell as Administrator 2. Run wsl --install 3. Restart your computer 4. Relaunch Docker Desktop

For detailed instructions, see Microsoft's WSL installation guide.

Hyper-V Conflicts (Windows)

Symptom: Docker Desktop reports conflicts with Hyper-V or other virtualisation software (e.g., VirtualBox, VMware).

Solution: Switch to the WSL 2 backend, which avoids most Hyper-V conflicts. In Docker Desktop, go to Settings > General and ensure Use the WSL 2 based engine is checked. If you must use Hyper-V, other virtualisation products that do not support Hyper-V may need to be uninstalled or reconfigured.

"Docker Daemon Is Not Running" Error

Symptom: Running docker commands returns an error like "Cannot connect to the Docker daemon" or "docker daemon is not running."

Solution: Ensure Docker Desktop is open and fully started. Look for the Docker whale icon in your system tray or menu bar. If the icon is not present, launch Docker Desktop. It may take 30–60 seconds for the daemon to become ready after the application opens.

Port Conflicts

Symptom: Precision Bridge fails to start with an error about ports already being in use.

Solution: Another application may be using the same port (commonly 7502). Stop the conflicting application, or configure Precision Bridge to use a different port. To identify which process is using the port:

  • Windows: netstat -ano | findstr :7502
  • macOS: lsof -i :7502

Virtualisation Not Detected on a Cloud VM

Symptom: Docker Desktop reports "Virtualization support not detected", or WSL 2 fails with HCS_E_HYPERV_NOT_INSTALLED, even though Windows features look enabled. Common on Azure, AWS, and other cloud-hosted Windows VMs.

Solution: Docker Desktop requires nested virtualisation because it runs Linux containers inside a WSL 2 or Hyper-V virtual machine. Not every cloud VM size exposes the underlying virtualisation extensions to the guest OS.

On Microsoft Azure, the most common cause is the B-series (burstable) VMs — B1s, B2s, B2ms, and so on — which do not support nested virtualisation regardless of how Windows features are configured. Resize to a Dv3/Dsv3, Ev3/Esv3, or newer Intel series (for example Standard_D2s_v5), or move the install to a Linux VM with Docker Engine.

See Running in a Virtual Machine for the full diagnosis and a per-provider matrix.

Windows Server: Missing Prerequisites or Blank Manager Window

Symptom: On a Windows Server VM, Docker Desktop installs and starts, but the Precision Bridge Windows manager either does not open, launches with a blank white window, or crashes with 'NoneType' object has no attribute 'BrowserProcessId'. The native build can exhibit the same blank-window behaviour.

Cause: Server SKUs do not ship with several components the embedded WebView2 control depends on. Install all of the following on the server:

  • Microsoft Visual C++ Redistributable 2015–2022 (x64) from Microsoft.
  • Server-Media-Foundation feature: Install-WindowsFeature Server-Media-Foundation in an elevated PowerShell.
  • Microsoft Edge WebView2 Runtime: install the Evergreen Standalone Installer (x64) as Administrator so it registers machine-wide.

Server Core SKUs are not supported — the embedded WebView2 control requires a full GUI subsystem.

If the manager still fails to render after installing all of the above, this is a known limitation on Windows Server with no current workaround for the Docker install path. For a server-hosted deployment, use a Linux VM with Docker Engine instead. See Running in a Virtual Machine for the full breakdown.

Docker Desktop Not Starting After Windows Update

Symptom: Docker Desktop fails to open or crashes immediately after a Windows update.

Solution: 1. Try restarting your computer 2. If the issue persists, open PowerShell as Administrator and run wsl --update to ensure WSL 2 is up to date 3. If still failing, uninstall and reinstall Docker Desktop from the official website

Next Steps

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

Related articles

Comments

0 comments

Please sign in to leave a comment.

Powered by Zendesk