Docker

The Hubzoid image runs hubzoid run /hub against a hub folder you mount into the container. It is a drop-in replacement for a native install: the same processes, the same .env, the same public port.

When to use thisCopy Anchor Link

Use the image when pip install hubzoid is impractical on the host (PyAV build problems, the wrong Python version, missing system libraries), or when your platform runs containers. For the processes and data stores the container runs, see deployment topologies.

The imageCopy Anchor Link

The Dockerfile (opens in a new tab) at the repository root builds the image from the checked-out source with the reviewed dependency set in requirements.lock, so the image version is the version you checked out.

Only port 3080 is meant to be published. The edge on that port serves the chat app, download links, the Console at /portal/ and the hosted MCP server. The bridge listens on 127.0.0.1 inside the container and is never reachable from outside it.

The Docker path was not re-verified end to end for the 1.0.1 release, so run hubzoid doctor inside a new container before you rely on it.

Build and runCopy Anchor Link

Check out the release you want and build it:

git checkout v1.0.1
docker build -t hubzoid:1.0.1 .

Run one hub:

docker run -d --restart unless-stopped \
  --name devops-agent \
  -p 3080:3080 \
  -v "$PWD/devops-agent:/hub" \
  --env-file "$PWD/devops-agent/.env" \
  hubzoid:1.0.1

Arguments after the image name replace the default command, so hubzoid:1.0.1 run /hub --slack also starts the Slack adapter. Put a reverse proxy with TLS in front of port 3080, exactly as on a single server.

Published imagesCopy Anchor Link

The release pipeline in .github/workflows/ci.yml (opens in a new tab) runs when a vX.Y.Z tag is pushed. It runs the full test suite, builds the Console and the wheel, builds the image for amd64 and arm64, and checks that the image starts and keeps the bridge unreachable. Only then does it push the image to the GitHub Container Registry, followed by PyPI and the GitHub release:

docker pull ghcr.io/hubzoid/hubzoid:1.0.1

Each release is tagged with its version and latest. Pin the version tag in production. Building from the tag yourself gives the same result.

Docker ComposeCopy Anchor Link

The docker/ (opens in a new tab) folder holds three Compose files. The base file runs one hub on SQLite. The other two add to it.

HUB_PATH=$PWD/my-hub docker compose -f docker/docker-compose.yml up -d

PersistenceCopy Anchor Link

Everything a hub writes stays in the folder mounted at /hub, so it survives container replacement and hubzoid backup covers it.

With the PostgreSQL file, the database itself lives in the named volume hubzoid-pg. Back it up with pg_dump as described in backup and restore.

On Linux the container runs as an unprivileged user, so the mounted folder must be writable by it. For example, chown -R 999:999 my-hub, or run the container with --user "$(id -u):$(id -g)".

ConfigurationCopy Anchor Link

The hub reads its .env from the mounted folder at start, the same way a native install does. Values in that file win over variables in the container environment, including ones set by --env-file or a Compose environment: block. To drive a setting from the container environment instead, leave it out of the hub's .env.

The settings a public deployment needs are the same as on a server: MODEL and its provider key, BRIDGE_API_KEYS, and the sign-in block with WEBUI_AUTH=true, WEBUI_SECRET_KEY and WEBUI_URL. See single server and authentication.

Operator commandsCopy Anchor Link

Run operator commands inside the container against /hub:

docker compose -f docker/docker-compose.yml exec hubzoid hubzoid doctor /hub
docker compose -f docker/docker-compose.yml exec hubzoid hubzoid backup /hub --out /hub/backup.tar.gz
docker compose -f docker/docker-compose.yml exec hubzoid hubzoid schedule status /hub

For liveness probes, the public port answers Open WebUI's /health endpoint.

Upgrading the containerCopy Anchor Link

Back up, stop the container, pull or build the new image, and start again. The new version upgrades Hubzoid's tables at its first start. Read upgrading before moving between minor versions.

Container platformsCopy Anchor Link

The image is the entry point for ECS, Kubernetes and other orchestrators. Two rules keep a hub's data safe there:

• One task or pod per hub. Give each hub its own service with a desired count of 1 and no horizontal autoscaling. Several processes writing one SQLite database corrupt it.
• No SQLite on a network filesystem. Keep webui.db and the .hubzoid databases on block storage such as an EBS volume. With a network filesystem such as EFS, mount it only for uploads, keep the databases on the task's own storage, and snapshot them on a schedule. Or move Hubzoid's stores to PostgreSQL.

The container listens on PORT (default 3080) and accepts .env values as container environment variables.

What differs in a containerCopy Anchor Link

Next stepsCopy Anchor Link

Read this page as Markdown