Self-host - Docker (pre-built images)

Pull published OpenQuok self-host container images from GHCR or Docker Hub — registry env vars, version tags, updates, and when to rebuild the web image.

3 min read

Connect your agent today

Draft from chat, review in your calendar, and publish only what you approve.

Start for $0

Overview

Maintainers publish container images for the self-host stack. You can pull the API, workers, and (optionally) the agent server instead of compiling them locally.

The usual path is still: clone the repo, configure infra/self-host/.env, and run Compose. See Docker Compose (self-host). Use this page when you want registry images on the same CPU architecture as the build (amd64 or arm64).

Release tags look like self-host-v1.0.0 on git; images use 1.0.0 and latest.

Registries

Registry	Prefix
GitHub Container Registry (default)	ghcr.io/ratimon
Docker Hub	docker.io/ratimon

Image	Services
openquok-api	`api`
openquok-orchestrator	three `worker-*` services
openquok-web	`web` (usually you build locally)
openquok-agent-server	`agent-server` with `cli` profile

Example: docker pull ghcr.io/ratimon/openquok-api:latest

Package pages: openquok-api on GHCR, ratimon on Docker Hub.

Pin a version with OPENQUOK_IMAGE_TAG in infra/self-host/.env (for example 1.0.0 instead of latest).

Env vars for pulls

Variable	Default	Role
OPENQUOK_IMAGE_REGISTRY	`ghcr.io/ratimon`	Registry host and org
OPENQUOK_IMAGE_TAG	`latest`	Tag for all `openquok-*` images
OPENQUOK_PULL_WEB	`false`	Set `true` only when your VITE_* match the published web image

Base file: infra/self-host/docker-compose.yml. Add overlay infra/self-host/docker-compose.images.yml for registry-first pulls.

Web image

VITE_* are baked in at web build time. If your Supabase URL, keys, or public site URL differ from the CI defaults, build web locally. Do not set OPENQUOK_PULL_WEB unless you know the pulled image matches your project.

There is no runtime injection of VITE_* today. Treat pulled openquok-web as a localhost demo shortcut, not a replacement for compose build web on a real Supabase project.

Pull and start

Prerequisites: System requirements and Supabase keys from Docker Compose.

Configure `.env`

Copy infra/self-host/.env.example to infra/self-host/.env. Fill Supabase and SECURITY_SECRET.

Optional:

OPENQUOK_IMAGE_REGISTRY=ghcr.io/ratimon
OPENQUOK_IMAGE_TAG=latest

Pull images

From the repository root:

docker compose -f infra/self-host/docker-compose.yml -f infra/self-host/docker-compose.images.yml pull

This pulls API, orchestrator, and (with —profile cli) agent server. Web still builds by default.

Start

docker compose -f infra/self-host/docker-compose.yml -f infra/self-host/docker-compose.images.yml up -d --build

The first web build can take 15–30 minutes or more. Later restarts are faster.

Open http://localhost:4007. For restarts without rebuild, see Start again on the Compose page (use both -f files).

Optional: pulled web (advanced)

Only when your URLs and Supabase publishable keys match the CI bake:

Set OPENQUOK_PULL_WEB=true.
Uncomment the web: block in docker-compose.images.yml.
Run pull, then up -d without —build for web.

Optional: CLI profile

Add —profile cli to pull and up when you need device-flow login. Same as Docker Compose.

Choose an approach

Approach	When
One compose file + `up —build`	Default; custom VITE_*
Base + images overlay + `pull`	Faster API and workers; you still build web
Pinned OPENQUOK_IMAGE_TAG	You want a fixed release version