From 1be0aa10db1c0352c064f2ce480e24f5e509a6d5 Mon Sep 17 00:00:00 2001 From: awphi <26072111+awphi@users.noreply.github.com> Date: Mon, 24 Aug 2026 15:25:24 +0100 Subject: [PATCH 1/5] docs: docker install guide Signed-off-by: awphi <26072111+awphi@users.noreply.github.com> --- docs/introduction/container-engines.md | 95 ++++++++++++++++++++++++++ 1 file changed, 95 insertions(+) create mode 100644 docs/introduction/container-engines.md diff --git a/docs/introduction/container-engines.md b/docs/introduction/container-engines.md new file mode 100644 index 00000000..063e092e --- /dev/null +++ b/docs/introduction/container-engines.md @@ -0,0 +1,95 @@ +--- +sidebar_position: 2 +--- + +# Install Docker for Topo + +Topo uses Docker to build container images on the [host](glossary.md#host) and run containers on the [target](glossary.md#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. + +Configure the host user and target SSH user to run `docker` commands without `sudo`. + +:::caution + +On Linux, membership in the `docker` group grants root-level privileges. Review the [Docker daemon security guidance](https://docs.docker.com/engine/security/#docker-daemon-attack-surface) before you grant access. + +::: + +## Install Docker on the host + +Choose one of the following installation methods. Docker Desktop is the simplest option. Rancher Desktop, Colima, and Docker Engine provide open source alternatives for supported systems. + +### Docker Desktop + +[Docker Desktop](https://docs.docker.com/desktop/) includes Docker Engine, the Docker CLI, and Docker Compose. It is available for supported macOS, Windows, and Linux systems. + +:::note + +Review the [Docker Desktop license terms](https://docs.docker.com/subscription/desktop-license/) before installation. Some organizations and types of commercial use require a paid subscription. + +::: + +Follow the [Docker Desktop installation instructions](https://docs.docker.com/desktop/setup/install/) for your host. On Windows, configure Docker Desktop to use Linux containers. + +Start Docker Desktop before you use Topo, and keep it running. Signing in to Docker Desktop is optional unless your organization requires it. Sign in to [increase Docker Hub pull limits, access private images, or apply organization security policies](https://docs.docker.com/desktop/setup/sign-in/). + +### Rancher Desktop + +[Rancher Desktop](https://rancherdesktop.io/) is an open source desktop application for macOS, Windows, and Linux. It includes the Docker CLI and Docker Compose. + +Follow the [Rancher Desktop installation instructions](https://docs.rancherdesktop.io/getting-started/installation/) for your host. When Rancher Desktop starts for the first time, select **dockerd (moby)** as the container engine. Topo does not require Kubernetes. You can change these settings later in **Preferences**. + +Start Rancher Desktop before you use Topo, and keep it running. + +### Colima + +[Colima](https://colima.run/) provides container runtimes in a Linux virtual machine on macOS and Linux. Colima uses the Docker runtime by default, but you must install the Docker CLI and Docker Compose separately. + +Follow the [Colima installation instructions](https://colima.run/docs/installation/). To install Colima and the required Docker tools with Homebrew, run: + +```sh +brew install colima docker docker-compose +mkdir -p ~/.docker/cli-plugins +ln -sfn "$(brew --prefix)/opt/docker-compose/bin/docker-compose" ~/.docker/cli-plugins/docker-compose +``` + +Start Colima with the Docker runtime: + +```sh +colima start +``` + +Keep Colima running while you use Topo. Do not start Colima with the `containerd` runtime. + +### Docker Engine on Linux + +[Docker Engine](https://docs.docker.com/engine/) provides a native, open source container engine for Linux without a desktop application. + +Follow the [Docker Engine installation instructions](https://docs.docker.com/engine/install/) for your Linux distribution. Install the [Docker Compose plugin](https://docs.docker.com/compose/install/linux/) if your installation method does not include it. + +Complete the relevant [Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/). Configure Docker to start when the host starts, and enable your user to run `docker` commands without `sudo`. + +## Install Docker on the target + +The target must run Linux on AArch64 (`linux/arm64`). Follow the [Docker Engine installation instructions](https://docs.docker.com/engine/install/) for the target distribution. + +Complete the relevant [Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/). Configure Docker to start when the target starts, and enable the SSH user to run `docker` commands without `sudo`. + +For a custom Linux distribution built with the Yocto Project, use the [`meta-virtualization`](https://layers.openembedded.org/layerindex/branch/master/layer/meta-virtualization/) branch that matches your Yocto Project release. + +## Verify installation + +Run the Topo health checks for the host and target: + +```sh +topo health --target user@target.example +``` + +Replace `user@target.example` with the SSH destination for your target. + +A successful Docker installation reports: + +- `Container Engine: ✅` under both `Host` and `Target` +- `Docker Compose: ✅` under `Host` From f370082d06ffc1696137e3c49b17a31b3508224a Mon Sep 17 00:00:00 2001 From: awphi <26072111+awphi@users.noreply.github.com> Date: Mon, 24 Aug 2026 16:04:14 +0100 Subject: [PATCH 2/5] wsl note Signed-off-by: awphi <26072111+awphi@users.noreply.github.com> --- docs/introduction/container-engines.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/introduction/container-engines.md b/docs/introduction/container-engines.md index 063e092e..aa169efe 100644 --- a/docs/introduction/container-engines.md +++ b/docs/introduction/container-engines.md @@ -39,6 +39,12 @@ Start Docker Desktop before you use Topo, and keep it running. Signing in to Doc [Rancher Desktop](https://rancherdesktop.io/) is an open source desktop application for macOS, Windows, and Linux. It includes the Docker CLI and Docker Compose. +:::note + +On Windows, install [Windows Subsystem for Linux 2 (WSL 2)](https://aka.ms/wslinstall) before you install Rancher Desktop. + +::: + Follow the [Rancher Desktop installation instructions](https://docs.rancherdesktop.io/getting-started/installation/) for your host. When Rancher Desktop starts for the first time, select **dockerd (moby)** as the container engine. Topo does not require Kubernetes. You can change these settings later in **Preferences**. Start Rancher Desktop before you use Topo, and keep it running. From 56a105d4674d6abea32b1736905323d6aa36ce3b Mon Sep 17 00:00:00 2001 From: awphi <26072111+awphi@users.noreply.github.com> Date: Mon, 24 Aug 2026 16:29:07 +0100 Subject: [PATCH 3/5] path note Signed-off-by: awphi <26072111+awphi@users.noreply.github.com> --- docs/introduction/container-engines.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/introduction/container-engines.md b/docs/introduction/container-engines.md index aa169efe..edbbec0d 100644 --- a/docs/introduction/container-engines.md +++ b/docs/introduction/container-engines.md @@ -47,6 +47,8 @@ On Windows, install [Windows Subsystem for Linux 2 (WSL 2)](https://aka.ms/wslin Follow the [Rancher Desktop installation instructions](https://docs.rancherdesktop.io/getting-started/installation/) for your host. When Rancher Desktop starts for the first time, select **dockerd (moby)** as the container engine. Topo does not require Kubernetes. You can change these settings later in **Preferences**. +On macOS and Linux, select **Automatic** to add the Rancher Desktop tools to `PATH`. If you select **Manual**, add `~/.rd/bin` to `PATH` yourself. + Start Rancher Desktop before you use Topo, and keep it running. ### Colima From 525877dd00bd3decd0d3ebfa23bb6157dfa3c538 Mon Sep 17 00:00:00 2001 From: awphi <26072111+awphi@users.noreply.github.com> Date: Mon, 24 Aug 2026 17:22:10 +0100 Subject: [PATCH 4/5] cross-links Signed-off-by: awphi <26072111+awphi@users.noreply.github.com> --- README.md | 8 ++++++-- docs/introduction/install.mdx | 2 +- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 0587ff43..36c87e32 100644 --- a/README.md +++ b/README.md @@ -63,17 +63,21 @@ Not sure what these terms mean? The [glossary](docs/introduction/glossary.md) de **Host machine** (where you run `topo`): -- [Docker](https://docs.docker.com/get-docker/) +- [Docker](#install-docker) - OpenSSH Client **Target machine** (the remote Arm system): - Reachable with SSH - Linux on ARM64 -- Docker +- [Docker](#install-docker) The host and target can be the same system. If you're working directly on an Arm Linux system, use `--target localhost`. +### Install Docker + +See [Install Docker for Topo](docs/introduction/container-engines.md) for supported installation methods and verification steps. + ### Linux and macOS Using [Homebrew](https://github.com/arm/homebrew-topo): diff --git a/docs/introduction/install.mdx b/docs/introduction/install.mdx index 186f7d11..c411bf17 100644 --- a/docs/introduction/install.mdx +++ b/docs/introduction/install.mdx @@ -25,7 +25,7 @@ A target must run Linux on AArch64 (`linux/arm64`). Topo uses Docker to build im Install the following tools on the host: -- [Docker](https://docs.docker.com/get-docker/) +- [Docker](container-engines.md) - OpenSSH client - Git to clone [Topo Projects](glossary.md#topo-project) from Git repositories From 495613476e5f80792649db176fe3aa7251215907 Mon Sep 17 00:00:00 2001 From: awphi <26072111+awphi@users.noreply.github.com> Date: Tue, 25 Aug 2026 10:15:16 +0100 Subject: [PATCH 5/5] simplifyyyyy maaan Signed-off-by: awphi <26072111+awphi@users.noreply.github.com> --- docs/introduction/container-engines.md | 98 +++++++------------------- 1 file changed, 27 insertions(+), 71 deletions(-) diff --git a/docs/introduction/container-engines.md b/docs/introduction/container-engines.md index edbbec0d..7070d3cf 100644 --- a/docs/introduction/container-engines.md +++ b/docs/introduction/container-engines.md @@ -9,95 +9,51 @@ Topo uses Docker to build container images on the [host](glossary.md#host) and r - 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. -Configure the host user and target SSH user to run `docker` commands without `sudo`. +## Check container engines with Topo health -:::caution - -On Linux, membership in the `docker` group grants root-level privileges. Review the [Docker daemon security guidance](https://docs.docker.com/engine/security/#docker-daemon-attack-surface) before you grant access. - -::: - -## Install Docker on the host - -Choose one of the following installation methods. Docker Desktop is the simplest option. Rancher Desktop, Colima, and Docker Engine provide open source alternatives for supported systems. - -### Docker Desktop - -[Docker Desktop](https://docs.docker.com/desktop/) includes Docker Engine, the Docker CLI, and Docker Compose. It is available for supported macOS, Windows, and Linux systems. - -:::note - -Review the [Docker Desktop license terms](https://docs.docker.com/subscription/desktop-license/) before installation. Some organizations and types of commercial use require a paid subscription. - -::: - -Follow the [Docker Desktop installation instructions](https://docs.docker.com/desktop/setup/install/) for your host. On Windows, configure Docker Desktop to use Linux containers. - -Start Docker Desktop before you use Topo, and keep it running. Signing in to Docker Desktop is optional unless your organization requires it. Sign in to [increase Docker Hub pull limits, access private images, or apply organization security policies](https://docs.docker.com/desktop/setup/sign-in/). - -### Rancher Desktop - -[Rancher Desktop](https://rancherdesktop.io/) is an open source desktop application for macOS, Windows, and Linux. It includes the Docker CLI and Docker Compose. - -:::note - -On Windows, install [Windows Subsystem for Linux 2 (WSL 2)](https://aka.ms/wslinstall) before you install Rancher Desktop. - -::: - -Follow the [Rancher Desktop installation instructions](https://docs.rancherdesktop.io/getting-started/installation/) for your host. When Rancher Desktop starts for the first time, select **dockerd (moby)** as the container engine. Topo does not require Kubernetes. You can change these settings later in **Preferences**. - -On macOS and Linux, select **Automatic** to add the Rancher Desktop tools to `PATH`. If you select **Manual**, add `~/.rd/bin` to `PATH` yourself. - -Start Rancher Desktop before you use Topo, and keep it running. - -### Colima - -[Colima](https://colima.run/) provides container runtimes in a Linux virtual machine on macOS and Linux. Colima uses the Docker runtime by default, but you must install the Docker CLI and Docker Compose separately. - -Follow the [Colima installation instructions](https://colima.run/docs/installation/). To install Colima and the required Docker tools with Homebrew, run: +After you install Topo, run the health check: ```sh -brew install colima docker docker-compose -mkdir -p ~/.docker/cli-plugins -ln -sfn "$(brew --prefix)/opt/docker-compose/bin/docker-compose" ~/.docker/cli-plugins/docker-compose +topo health --target [user@]host ``` -Start Colima with the Docker runtime: +`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. -```sh -colima start -``` +- For a host container engine or Docker Compose error, [choose a host installation](#choose-a-host-installation). +- For a target container engine error, [install Docker on the target](#install-docker-on-the-target). -Keep Colima running while you use Topo. Do not start Colima with the `containerd` runtime. +## Choose a host installation -### Docker Engine on Linux +Topo recommends Docker Desktop where it is supported. Otherwise, use the alternative for your host: -[Docker Engine](https://docs.docker.com/engine/) provides a native, open source container engine for Linux without a desktop application. +| Host | Recommendation | +| ------------- | ----------------------------------------------------------------------------------------------------------------------- | +| macOS | [Docker Desktop](https://docs.docker.com/desktop/setup/install/mac-install/) or [Colima](#colima) | +| Linux x86_64 | [Docker Desktop](https://docs.docker.com/desktop/setup/install/linux/) or [Docker Engine](#docker-engine-on-linux) | +| Linux Arm64 | [Docker Engine](#docker-engine-on-linux) | +| Windows x64 | [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) or [Rancher Desktop](#rancher-desktop) | +| Windows Arm64 | [Docker Desktop](https://docs.docker.com/desktop/setup/install/windows-install/) (Early Access) | -Follow the [Docker Engine installation instructions](https://docs.docker.com/engine/install/) for your Linux distribution. Install the [Docker Compose plugin](https://docs.docker.com/compose/install/linux/) if your installation method does not include it. +The table shows Topo recommendations, not every platform that each container engine supports. -Complete the relevant [Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/). Configure Docker to start when the host starts, and enable your user to run `docker` commands without `sudo`. +Review the [Docker Desktop license terms](https://docs.docker.com/subscription/desktop-license/) before installation. On Windows, use Linux containers. -## Install Docker on the target +### Colima -The target must run Linux on AArch64 (`linux/arm64`). Follow the [Docker Engine installation instructions](https://docs.docker.com/engine/install/) for the target distribution. +Follow the [Colima installation instructions](https://colima.run/docs/installation/), including the steps to install the Docker CLI and [Docker Compose plugin](https://colima.run/docs/installation/#docker-compose-plugin). Use Colima's default Docker runtime. -Complete the relevant [Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/). Configure Docker to start when the target starts, and enable the SSH user to run `docker` commands without `sudo`. +### Docker Engine on Linux -For a custom Linux distribution built with the Yocto Project, use the [`meta-virtualization`](https://layers.openembedded.org/layerindex/branch/master/layer/meta-virtualization/) branch that matches your Yocto Project release. +Follow the [Docker Engine installation instructions](https://docs.docker.com/engine/install/) for your distribution. -## Verify installation +Also install the [Docker Compose plugin](https://docs.docker.com/compose/install/linux/) and complete the [Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/) so your user can run `docker` without `sudo`. Access to the Docker daemon grants [root-level privileges](https://docs.docker.com/engine/security/#docker-daemon-attack-surface). -Run the Topo health checks for the host and target: +### Rancher Desktop -```sh -topo health --target user@target.example -``` +Follow the [Rancher Desktop installation instructions](https://docs.rancherdesktop.io/getting-started/installation/). Select **dockerd (moby)** as the container engine. Topo does not require Kubernetes. -Replace `user@target.example` with the SSH destination for your target. +## Install Docker on the target -A successful Docker installation reports: +The target must run Linux on AArch64 (`linux/arm64`). Follow the [Docker Engine installation instructions](https://docs.docker.com/engine/install/) for the target distribution, then complete the [Linux post-installation steps](https://docs.docker.com/engine/install/linux-postinstall/) so the target SSH user can run `docker` without `sudo`. -- `Container Engine: ✅` under both `Host` and `Target` -- `Docker Compose: ✅` under `Host` +For a custom Linux distribution built with the Yocto Project, see [`meta-virtualization`](https://layers.openembedded.org/layerindex/branch/master/layer/meta-virtualization/).