Install a container engine for Topo
Topo uses a container engine to build images on the host and run containers on the target. The target must run Linux on AArch64 (linux/arm64). Choose one engine for both systems:
Check container engines with Topo health
After you install Topo, run the health check:
topo health --target [user@]host
topo health checks the selected container engine on both the host and target. It also checks the Compose provider on the host. For Podman, add --engine podman. Follow any recommended actions and run the health check again after each change.
See the setup instructions for your selected engine below.
Docker
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.
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.
Podman
Select Podman
Set TOPO_ENGINE=podman in your environment to tell Topo to use Podman for any command where a container engine is required. Alternatively, specify the --engine flag on a per command basis (this takes precedence over TOPO_ENGINE). The selected engine applies to both the host and target.
Podman deployments do not support Compose services with a runtime: setting, including projects that require Remoteproc Runtime. Use Docker for those projects.
Install Podman on the host
Install Podman and configure podman compose to use Docker Compose. Topo uses Podman’s configured Compose provider. podman-compose is not a substitute. See Podman’s Compose configuration.
On macOS and Windows, initialise and start a Podman machine. On Linux, ensure the host Podman API socket is running using the socket setup below.
Install Podman on the target
Install Podman so that the SSH user can run podman without sudo. Compose is not required on the target. Enable the API socket as described below.
Enable the Podman API socket
Topo queries the target Podman API from the host through a temporary SSH tunnel. Being able to run podman on the target is not enough: its API socket must also be functional and accessible to the SSH user.
For rootless Podman on systemd, run as the SSH user (or the local user on the host):
systemctl --user enable --now podman.socket
For other setups and keeping the service available after logout, see the Podman API service documentation. Keep the socket restricted to that user, and ensure the target SSH server allows forwarding.