Docker and Companion Hub

Companion Hub is a management layer on top of Docker. Understanding a few Docker concepts helps you troubleshoot issues, back up data, and know what happens when you install or remove apps.

Core concepts

Image

An image is a read-only template — a snapshot of an application and its dependencies. When you install Nextcloud from the App Store, Hub pulls the nextcloud:latest image from a registry (usually Docker Hub or GHCR). Images are cached on disk and can be reused by many containers.

Container

A container is a running instance of an image. Each app you install gets one or more containers. When you click Stop on an app card, Hub stops its container(s) but keeps the image and your data.

Volume

A volume (or bind mount) is persistent storage attached to a container. App databases, uploads, and configuration live here — typically under your Hub data directory (ROOT_FOLDER_HOST), and some apps use Docker-managed named volumes instead. Stopping or removing a container does not delete volumes unless you explicitly choose to remove them.

Compose

Docker Compose defines how multiple containers work together (networks, ports, dependencies). Each App Store entry ships a docker-compose.json (or legacy .yml) that Hub renders into a compose project per app.

How the pieces relate

One image can back many containers, and each container keeps its data in volumes that outlive it — stopping or removing a container leaves both the image and the volume in place:

flowchart TD
    R["Registry<br/>Docker Hub or GHCR"] -->|"pull"| I["Image<br/>read-only template, cached on disk"]
    K["docker-compose.json<br/>from the App Store entry"] -->|"rendered into one<br/>compose project per app"| C
    I -->|"run: one or more per app"| C["Container<br/>running instance"]
    C -->|"reads and writes"| V["Volume<br/>typically under ROOT_FOLDER_HOST"]

The four terms at a glance

What Hub manages for you

When you install an app, Hub:

1. Pulls the required Docker images
2. Generates an app.env file from your form inputs and Hub settings
3. Publishes the app’s port for local access and, when you expose the app publicly, adds Traefik routing for its public address. The app’s page lists each address — see Finding your app’s URL
4. Starts the compose stack and tracks status via Server-Sent Events

When you uninstall, Hub removes the app’s containers, images, and installed files, and the dialog shows one switch, Delete all data, which is on by default. With it on, Hub also deletes the app’s data folder, Docker volumes, and backups. With it off, all three stay, and the dialog says This app’s data and backups stay on this Hub.

Inspecting Docker state

Use the Hub dashboard (Settings → System) or the CLI:

cihub app list              # every Docker container on the host
cihub app status            # color-coded status + ports
cihub app inspect <name>    # ports, env vars, mounts
cihub status                # Hub stack health + networking

Direct Docker commands also work:

docker ps                   # running containers
docker compose ls           # compose projects
docker system df            # disk usage by images/volumes

Cleaning up Docker state

Over time, unused images and stopped containers consume disk space.

Safe cleanup (unused resources only)

docker system prune         # stopped containers, unused networks
docker image prune          # dangling images only
docker system df            # check usage first

Aggressive cleanup (re-downloads images later)

docker system prune -a      # all unused images

Full Hub reset

To return Hub to a first-time state, use one of these. Each one deletes your operators, installed apps, registration, and local app data.

• Settings → System → Factory reset Hub. You confirm by typing the device’s name. Use this while Hub is running.
• cihub reset --yes from a terminal, for when the Hub API is down. Run cihub reset --dry-run first to see the apps, containers, and folders it would remove. Without --yes, the CLI asks for confirmation.

Removing Cloudflare tunnel credentials

If you unpair from your CI Account or need to reset remote access, Hub clears the tunnel token during registration reset. You can also remove it manually:

1. In the Hub dashboard: Settings → Network → This Hub in your account → Reset this Hub only. This clears the Hub’s pairing. The Portal keeps the device, its web addresses, and its apps until an owner or admin deletes them there.
2. On disk: delete the token file in the tunnel folder next to your data root, for example ~/.local/share/tunnel/token on Linux. See Folder structure.
3. Restart the Hub stack: cihub down && cihub up prod --detached

Hub starts the cloudflared container only for a paired Hub, when the tunnel folder holds both a token and a registration.json file. After you remove the credentials, the container stays stopped until you pair again and your CI Account provisions a new tunnel.

Hub stack containers

The Hub itself runs as a Docker Compose project. Typical containers include:

App containers are separate compose projects managed alongside the Hub stack. Older stacks used the names ci-os-hub and ci-os-hub-queue, which still resolve as network aliases.

Leaving without lock-in

Every app runs as standard Docker Compose. If you ever stop using Hub, your containers and volumes remain on disk. Each app’s rendered compose file is apps/<store>/<app>/docker-compose.yml and its environment is app-data/<store>/<app>/app.env, both under your data root. You can start an app manually by running docker compose --env-file <app.env> -f <docker-compose.yml> up -d.