Install Docker for Topo
Topo uses Docker to build container images on the host and run containers on the target. Install the following components:
- On the host, install the Docker command-line interface (CLI), a running Docker-compatible engine, and Docker Compose 2.21.0 or later as a Docker CLI plugin.
- On the target, install Docker Engine and the Docker CLI. Docker Compose is not required on the target.
Check container engines with Topo health
After you install Topo, run the health check:
topo health --target [user@]host
topo health checks the container engine on both the host and target. It also checks Docker Compose on the host. Follow any recommended actions and run the health check again after each change.
- For a host container engine or Docker Compose error, choose a host installation.
- For a target container engine error, install Docker on the target.
Choose a host installation
Topo recommends Docker Desktop where it is supported. Otherwise, use the alternative for your host:
| Host | Recommendation |
|---|---|
| macOS | Docker Desktop or Colima |
| Linux x86_64 | Docker Desktop or Docker Engine |
| Linux Arm64 | Docker Engine |
| Windows x64 | Docker Desktop or Rancher Desktop |
| Windows Arm64 | Docker Desktop (Early Access) |
The table shows Topo recommendations, not every platform that each container engine supports.
Review the Docker Desktop license terms before installation. On Windows, use Linux containers.
Colima
Follow the Colima installation instructions, including the steps to install the Docker CLI and Docker Compose plugin. Use Colima's default Docker runtime.
Docker Engine on Linux
Follow the Docker Engine installation instructions for your distribution.
Also install the Docker Compose plugin and complete the Linux post-installation steps so your user can run docker without sudo. Access to the Docker daemon grants root-level privileges.
Rancher Desktop
Follow the Rancher Desktop installation instructions. Select dockerd (moby) as the container engine. Topo does not require Kubernetes.
Install Docker on the target
The target must run Linux on AArch64 (linux/arm64). Follow the Docker Engine installation instructions for the target distribution, then complete the Linux post-installation steps so the target SSH user can run docker without sudo.
For a custom Linux distribution built with the Yocto Project, see meta-virtualization.