Install Docker
Time: about 15 minutes · You’ll need: admin rights on your machine
Companion Hub runs every app as a Docker container. This walkthrough installs Docker, proves it works, and shows you what Hub is doing with it — so that when something breaks later, you know where to look.
If you already run Docker, skip to Check what you have.
You don’t need to understand Docker to use Companion Hub. You do need it installed and running. This page gets you there; Docker & Companion Hub explains the concepts afterwards.
Check what you have
Run this first — if Docker is already installed, you can skip most of this page:
docker --versionIf it works, you’ll see something like:
Docker version 27.3.1, build ce12230If 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’s the simplest option, but 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:
| Platform | Docker Desktop | Licensing-free alternative |
|---|---|---|
| macOS | Supported | Colima — Docker Engine in a lightweight VM |
| Windows | Supported | Docker Engine inside WSL2 |
| Linux | Supported | Docker Engine — already licensing-free |
You may not need to install anything manually. Hub’s setup wizard detects a missing engine and offers to install one for you — Auto-Install Docker Engine in WSL2 on Windows, or Colima on macOS. If you’d rather let Hub handle it, skip to Installing Companion Hub and come back only if the wizard reports a problem.
This page covers installing Docker Desktop yourself, plus Docker Engine on Linux. For the licensing-free routes on macOS and Windows, see Docker backends.
On a Linux server or VPS, use Docker Engine. Docker Desktop needs a desktop session and KVM, and its VM costs you memory you’d rather give to your apps.
Install Docker Desktop
macOS
- Download from docker.com/products/docker-desktop — pick Apple silicon or Intel chip to match your Mac
- Open the
.dmgand drag Docker to Applications - Launch Docker from Applications and accept the service agreement
- Wait for the whale icon in your menu bar to stop animating — that means the engine is running
On every platform, Docker Desktop must be running, not just installed. If you quit it, Companion Hub stops with it. Turn on the “start Docker Desktop when you sign in” option in Docker’s settings now.
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 | shDo not install docker.io or docker-compose from your distribution’s
package manager. Those packages are frequently too old and ship the obsolete
standalone docker-compose binary rather than the docker compose plugin
Hub requires.
Then add yourself to the docker group so you don’t need sudo for every command:
sudo usermod -aG docker $USERLog out and back in for the group change to take effect. This step is easy to skip and causes the most common Linux error — see Permission denied below.
This step is only needed for Docker Engine. Docker Desktop for Linux uses a socket owned by your own user, so there’s no group to join.
Verify it works
Three checks, in order. Don’t move on until all three pass.
Is the engine running?
docker infoYou should see a block of configuration ending in something like Server Version: 27.3.1.
If you get Cannot connect to the Docker daemon, the engine isn’t running. Launch Docker Desktop and wait for the whale icon to settle — on any platform, including Linux.
For Docker Engine on Linux, start the service instead:
sudo systemctl start docker && sudo systemctl enable dockerRunning Docker Desktop and Docker Engine on the same Linux machine is
possible, but they are separate daemons with separate containers. Check which
one you’re talking to with docker context ls — the active context is marked
with a *.
Can you run a container?
docker run --rm hello-worldDocker downloads a tiny test image and runs it. Expected output:
Hello from Docker!
This message shows that your installation appears to be working correctly.
...This proves the whole chain works: Docker can reach the registry, pull an image, and run a container.
Is the Compose plugin available?
docker compose versionExpected:
Docker Compose version v2.29.7Companion Hub defines every app as a Compose project, so this is not optional. If you get docker: 'compose' is not a docker command, you have Docker without the Compose plugin — reinstall using the official instructions for your platform above.
All three passed? Docker is ready. Next: Install Ollama for local AI, or go straight to Installing Companion Hub.
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 psYou’ll see the Hub’s own containers (ci-os-hub, ci-hub-db, ci-os-hub-queue, ci-hub-traefik) alongside a container for each app you installed.
That’s the whole trick: Hub is a friendly 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 lsThis lists Compose projects — one for the Hub stack, one per app.
Common problems
Permission denied
permission denied while trying to connect to the Docker daemon socketThis affects Docker Engine on Linux: you’re not in the docker group, or you haven’t logged out since being added.
sudo usermod -aG docker $USERThen log out and back in. Verify with:
docker run --rm hello-worldIf 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 dockerHub can’t find the Docker socket
Companion Hub mounts the Docker socket so it can manage app containers. It looks for Docker Desktop’s socket first ($XDG_RUNTIME_DIR/docker.sock, then ~/.docker/run/docker.sock) and falls back to Docker Engine’s /var/run/docker.sock.
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 point Hub at it explicitly by setting DOCKER_SOCKET_PATH in your Hub .env file to that path, without the unix:// prefix:
DOCKER_SOCKET_PATH=/run/user/1000/docker.sockRestart the stack afterwards:
cihub down && cihub up prod --detachedNot enough disk space
Docker images are large — budget at least 20 GB free. Check what’s in use:
docker system dfReclaim space from stopped containers and dangling images:
docker system prunedocker system prune -a also removes cached images that aren’t currently in
use. It’s safe for your data, but apps will re-download their images on next
start, which takes time and bandwidth.
For more, see Docker Issues.