Install Docker

Time: about 15 minutes · You’ll need: admin rights on your machine

Companion Hub runs every app as a Docker container. Install Docker, verify that it works, and learn how Hub uses it so you know where to look if a problem occurs.

If you already run Docker, skip to Check what you have.

The page in one picture — whichever route you take, the same three checks at the end tell you Docker is ready:

flowchart TD
    A["docker --version"] -->|"prints a version"| V["Verify it works"]
    A -->|"command not found"| B{"Which machine?"}
    B -->|"macOS, Windows,<br/>Linux desktop"| C["Install Docker Desktop"]
    B -->|"Linux server<br/>or VPS"| D["Install Docker Engine<br/>get.docker.com"]
    C --> V
    D --> E["usermod -aG docker,<br/>then log out and in"]
    E --> V
    V --> V1["docker info"]
    V1 --> V2["docker run --rm hello-world"]
    V2 --> V3["docker compose version"]
    V3 --> N["Next: Install Ollama"]

Check what you have

Run this first — if Docker is already installed, you can skip most of this page:

docker --version

If it works, you’ll see something like:

Docker version 29.8.0, build 88096ef

If you see command not found, continue to installation below.

Docker Desktop or Docker Engine?

Docker Desktop is the graphical application — engine, Compose plugin, and a dashboard, available on all three platforms. It needs a paid subscription for organizations over 250 employees or $10M revenue.

Every platform also has a licensing-free alternative, and Hub supports all of them:

This page covers installing Docker Desktop yourself, plus Docker Engine on Linux. For the licensing-free routes on macOS and Windows, see Docker backends.

Install Docker Desktop

ls -l /dev/kvm

curl -fsSL https://get.docker.com | sh

sudo apt install ./docker-desktop-amd64.deb

Install Docker Engine (Linux)

If you’re on a server, or you’d rather not run a VM, install the engine directly. The official convenience script adds Docker’s repository and installs the engine plus the Compose plugin:

curl -fsSL https://get.docker.com | sh

Then add yourself to the docker group so you don’t need sudo for every command:

sudo usermod -aG docker $USER

Log out and back in for the group change to take effect. Skipping this step causes the most common Linux error — see Permission denied below.

Verify it works

Three checks, in order. Don’t move on until all three pass.

docker info

sudo systemctl start docker && sudo systemctl enable docker

docker run --rm hello-world

Hello from Docker!
This message shows that your installation appears to be working correctly.
...

docker compose version

Docker Compose version v2.40.0

See what Hub does with Docker

Once you’ve installed Hub and an app, come back and run this — it’s the fastest way to understand what Hub actually is:

docker ps

You’ll see the Hub’s own containers — ci-hub (the dashboard and API, port 5002), ci-hub-db (PostgreSQL), ci-hub-queue (RabbitMQ), and traefik (the router) — alongside a container for each app you installed. If you connected Cloudflare or Tailscale, cloudflared and hub-tailscale appear too.

Hub provides an interface over Docker. Every app on your dashboard is a container in that list. Nothing is hidden, and nothing locks you in — if you stopped using Hub tomorrow, those containers and their data would still be on your disk.

docker compose ls

This lists Compose projects — one named ci-hub for the Hub stack, one per app.

Common problems

Permission denied

permission denied while trying to connect to the Docker daemon socket

This affects Docker Engine on Linux: you’re not in the docker group, or you haven’t logged out since being added. The Hub startup screen reports the same problem as CI Hub can’t use Docker and shows the usermod command below.

sudo usermod -aG docker $USER

Then log out and back in. Verify with:

docker run --rm hello-world

If it works without sudo, you’re set. Docker Desktop doesn’t hit this — its socket belongs to your user already.

Cannot connect to the Docker daemon

The engine isn’t running. Launch Docker Desktop and wait for the whale icon to settle — this applies on Linux too, if that’s what you installed.

For Docker Engine on Linux:

sudo systemctl start docker

Hub can’t find the Docker socket

Companion Hub mounts the Docker socket so it can manage app containers. It picks the engine like this:

1. A CI_HUB_DOCKER_HOST or DOCKER_HOST environment variable, if you set one.
2. Otherwise, the engine that already holds the Hub containers.
3. Otherwise, on a fresh install, Docker Desktop if it’s reachable, then the first other engine it finds. On Linux it looks at your current Docker context, then Docker Desktop’s sockets (~/.docker/desktop/docker.sock, ~/.docker/run/docker.sock), then Docker Engine’s /var/run/docker.sock, then rootless Docker’s $XDG_RUNTIME_DIR/docker.sock and /run/user/<your uid>/docker.sock.

Hub records its choice in state/docker-engine.json in the Hub data folder.

If Hub reports it can’t reach Docker while docker info works fine for you, find the socket your daemon is actually using:

docker context inspect --format '{{.Endpoints.docker.Host}}'

Then start Hub with that address in the environment of the process that starts it:

CI_HUB_DOCKER_HOST=unix:///run/user/1000/docker.sock cihub up

Use the same variable when you launch the desktop app or companion-hub --detached. Don’t put DOCKER_SOCKET_PATH in the Hub .env file: the desktop app rewrites that file on every start and recomputes the socket path.

See Environment variables.

Not enough disk space

Docker images are large — budget at least 20 GB free. Check what’s in use:

docker system df

Reclaim space from stopped containers and dangling images:

docker system prune

For more, see Docker issues.