Installing Docker with the app

Every task runs inside a Docker container, so Borago Board needs Docker on the machine that runs the containers. You do not install it yourself. The app finds Docker when it is there, installs it when it is not, starts it when it is stopped, and fixes access when Docker refuses your user. This guide follows each of those paths on each platform, with the labels the app shows. The setup page has the same story in one table, and Why Docker says why containers at all.

Goal

Docker running, reachable by the app without a log-out, and on Linux the gVisor sandbox registered with it.

Before you start

The desktop app, installed and open. Docker is only ever installed and started from the desktop app or from a browser on the same network, never from the cloud board or a phone, which run no containers.
Your administrator password. On Linux the whole install is one prompt. On macOS and Windows the app asks for no password of its own, and Docker Desktop's installer asks its own questions.
On Linux, one of the distributions the app can install on. It recognises Ubuntu and its flavours, Linux Mint, Debian, Pop!_OS, Zorin OS, elementary OS, KDE neon and Fedora. Anywhere else it points you at Docker's own guide.
An internet connection. The Linux install downloads packages and the gVisor binaries. macOS and Windows download the Docker Desktop installer.

Steps

The app checks for Docker on every start and keeps checking while it runs. Nothing is shown until it is sure. A machine with no Docker gets a calm strip at the top of the board reading Docker is not set up on this machine. with a Set up Docker button, and on a fresh install the dialog behind that button opens by itself, once. The dialog is headed Set up Docker and names your system under the title. What happens next depends on the platform.

Ubuntu and its flavours

Kubuntu, Lubuntu, Xubuntu and Ubuntu MATE all count as Ubuntu. OS support lists where the one-prompt install has been verified.

Press Install Docker. The dialog says the board can install Docker with your administrator approval, and that it installs the distribution's own Docker packages and the gVisor sandbox behind one prompt with no log-out needed. The checklist has three rows, Download the gVisor sandbox (checksum-verified), Install Docker and gVisor (administrator approval) and Wait for the Docker engine.
Type your password once. The gVisor download happens first, without any privileges, and is checked against its published checksum. Then the operating system's own password dialog appears. Everything privileged runs inside that one approval.
Keep the app open. An amber strip at the top of the board asks you to keep the app open until the install finishes, with a Show progress button that reopens the dialog. The rows tick off as they complete, and the install step prints its own output as it goes.
Read the last row. A clean install ends with a green row reading Docker and gVisor installed successfully. Press Close. Docker is reachable at once, the strip is gone, and the project's container can be started.

Fedora

Fedora 40 and later use the same dialog and the same single prompt. The difference is under the hood, where the install uses Fedora's own Docker packages (the moby engine, Compose and Buildx) through dnf instead of apt. The checklist rows, the password prompt and the last row read the same as on Ubuntu.

Linux Mint

Mint is recognised as a Debian-based system and takes the Ubuntu path exactly, with the same three rows and one prompt. The same is true of Debian, Pop!_OS, Zorin OS, elementary OS and KDE neon, which the app recognises by the same rule.

Other Linux

On a distribution the app does not recognise, the dialog says the system is not one the board can install Docker on automatically and offers only Close. Install Docker Engine with the Compose plugin from Docker's install guide, add your user to the docker group, and come back to the app. On its next check it finds Docker. If Docker is running but refuses your user, the strip offers Fix access, described below. gVisor can then be added from Settings, then Docker, with Set up gVisor.

macOS

Docker on a Mac is Docker Desktop, which comes as a disk image you drag into Applications. The app downloads it, checks it, opens it, and waits for the drag.

On an Apple silicon Mac, install Rosetta 2 first if asked. Docker Desktop needs it. When it is missing the dialog says Docker Desktop needs Rosetta 2, which is not installed on this Mac. and shows one button, Agree to Apple's license and install Rosetta 2. Pressing it accepts Apple's software license on your behalf and runs Apple's own installer. Apple provides no way to remove Rosetta 2 afterwards, and the dialog says so. The Docker step is held back until this one is done. An Intel Mac skips this.
Press Download and open the installer. The rows are Download the official Docker Desktop installer (checksum-verified), Open the installer and a waiting row that says the board opens Docker once the copy has finished. The download comes from Docker's own site for your Mac's architecture and is checked against Docker's published checksum. A mismatch is refused and the file deleted.
Drag Docker into Applications. The disk image opens in Finder. Drag the Docker icon into the Applications folder. The app watches the copy and does not touch the bundle until it is complete, which is what stops macOS calling it damaged. No password is asked for the drag.
Answer Docker Desktop's own first run. Once the copy has landed the app opens Docker Desktop, which asks for its own permissions and shows its own license. The app accepts nothing on your behalf. When Docker's engine answers, the last row of the checklist turns green. Press Close. The disk image is ejected and the installer file removed.

The app waits up to fifteen minutes for Docker to appear. Ejecting the image, deleting the installer, or closing the installer's Finder window ends the wait with a sentence saying what happened, and Try again downloads it afresh.

Windows

Docker on Windows is Docker Desktop too, and needs WSL 2, which Docker's installer sets up.

Press Download and open the installer. The rows are Download the official Docker Desktop installer (checksum-verified), Open the installer and Waiting for the installer to finish. The download is checked against Docker's published checksum before it is opened.
Approve Windows' own prompt. Windows shows its permission prompt for the installer. The app raises no prompt of its own.
Follow Docker's installer. It may ask you to restart or log out to finish setting up WSL 2. Do that. The app finds Docker when you are back and the last row of the checklist turns green.

What the single Linux step does

The one administrator approval on Linux covers everything below, in this order, so you are never asked twice.

Installs the distribution's own Docker packages with the Compose and Buildx plugins, and enables the Docker service.
Adds your user to the docker group.
Installs the gVisor runtime binaries that were downloaded and checksum-verified before the prompt, registers the runtime with Docker, restarts Docker, and runs a sandboxed test container as root to prove it works. This half never fails the install. When it cannot complete, Docker still works and the last row says so.
Grants your user read and write access to the Docker socket for this session, so the app reaches Docker at once. This is what removes the log-out that a docker group change normally needs. The grant lasts until the socket is recreated, and after that the group membership carries on by itself. Where that grant is unavailable, the dialog ends with Restart Borago Board now, which restarts the app inside the new group.

gVisor is Linux only. Docker Desktop's virtual machine is the isolation on macOS and Windows, so the app never offers gVisor there and never warns about its absence. Security says what gVisor protects.

If it did not work

The password prompt was cancelled or the password was refused

The install stops at once. The failed row turns red, an error line under the checklist says the install did not complete and why, the manual commands appear under the heading Do it yourself - run these in a terminal: with a copy button beside each, and the footer shows Try again. Nothing is retried on its own. One press raises one prompt. A wrong password is handled inside the operating system's dialog, which owns its own retries.

The download failed

The gVisor download is retried a few times with widening gaps, and each retry is announced in the row's detail line. When it never lands, Docker is still installed and the last row is amber, Docker installed, without the gVisor sandbox. Project containers then run on Docker's default runtime. Try gVisor again repeats only the gVisor part, and Install it by hand folds out the commands. When the Docker Desktop installer cannot be downloaded or fails its checksum, the error says the download could not be completed and verified, the file is deleted rather than opened, and the manual command (Homebrew on a Mac, winget on Windows) is shown to fetch the same installer from Docker.

Docker is installed but not running

By default the app starts Docker itself before showing any warning. The switch is in Settings, then Docker, labelled Start Docker automatically, on by default. It fires once each time Docker goes down and never raises a password prompt on its own. After a few seconds an amber strip reads that Docker is starting and can take a minute. When the native Linux engine needs a password to start, the strip reads Docker is installed but not running. and adds that starting it needs your administrator password, with a Start Docker button and the manual command beside it. A password dialog appears only after you press. After a press the app watches for the engine for 90 seconds. If it does not come up the strip turns red with the reason, and the manual command stays there. On a Mac where Docker Desktop is still being copied into Applications the strip reads Docker Desktop is still being installed. and the app checks again on its own.

Docker is running but the app cannot reach it

On Linux this means your user is not in the docker group, or was added after the app started. The strip reads Docker is running, but this user cannot access it. with a Fix access button. The dialog behind it is headed Fix Docker access. Press Fix access for one administrator prompt, which adds your user to the group and grants access to the socket. The last row then reads Your user can reach Docker now. When the app itself still needs to restart to see the group, the row reads Your user was added to the docker group and the footer offers Restart Borago Board now. On a system without that restart tool the dialog says logging out of your desktop session and back in also works.

The app cannot find Docker at all

The app searches the usual places, including the ones an app started from Finder cannot see. If Docker is somewhere unusual, open Settings, then Docker, and fill in Docker path with Browse or by typing. Empty means auto-detect. A saved path that does not exist is reported in red under the field and ignored, and a line under the field names the path the app found on its own.

gVisor is missing on Linux

Docker works without it. The project's Containers tab shows an amber note that the container runs without sandbox isolation, with an Install gVisor button, and Settings, then Docker, shows Set up gVisor. Both open the dialog headed Set up gVisor sandboxing, whose Install gVisor button downloads the checksum-verified binaries, registers the runtime with one administrator prompt, restarts Docker, and proves a sandboxed container runs. Restarting Docker briefly stops running containers, so the app refuses to start while a task run is in progress. When the machine cannot run gVisor, the dialog states the reason, for example a kernel that is too old or Docker Desktop for Linux, and offers only Close.

Source as Markdown: /docs/guides/installing-docker.md · Updated 2026-09-29 · Was this right? Tell us