docs: document both deploy paths, registry knobs, measured resource usage

README + deployment guide now show three ways to run RoboCo — pull the pre-built images (docker-compose.registry.yml), build from source, or the local-dev flow — instead of only the dev path. Add the ROBOCO_REGISTRY / ROBOCO_VERSION knobs and the required ROBOCO_ENCRYPTION_KEY (which was missing) to .env.example, and fix a stale piragi reference there. usage.md drops the unmeasured per-agent RAM ceiling and records the figures measured on the live stack: RAM is low and Ollama-dominated, storage is the real cost (images share the agent-base layer). Idle numbers — peak under an active task is best read live with docker stats.
2026-08-03 07:23:24 +02:00 · 2026-06-16 20:38:49 +02:00
parent 1dc9e8e47a
commit 4441b23df4
4 changed files with 120 additions and 28 deletions
@@ -21,6 +21,16 @@
 # Claude auth directory to mount into orchestrator
 # CLAUDE_AUTH_DIR=~/.claude

+# =============================================================================
+# Container Images (docker-compose.registry.yml — pre-built deployment)
+# =============================================================================
+# Only used by docker-compose.registry.yml, which runs the published images
+# instead of building from source. Defaults shown.
+# Registry namespace: ghcr.io/rennf93 (GHCR) or docker.io/renzof93 (Docker Hub)
+# ROBOCO_REGISTRY=ghcr.io/rennf93
+# Image tag: latest, or a pinned release such as 0.5.0
+# ROBOCO_VERSION=latest
+
 # =============================================================================
 # Data Persistence
 # =============================================================================
@@ -65,7 +75,7 @@ ROBOCO_REDIS_DB=0
 # ROBOCO_REDIS_PASSWORD=

 # =============================================================================
-# RAG / Local LLM (Ollama + pgvector via piragi)
+# RAG / Local LLM (Ollama + in-house pgvector engine)
 # =============================================================================
 # For docker compose use the container name (roboco-ollama); locally, localhost.
 ROBOCO_OLLAMA_BASE_URL=http://localhost:11434
@@ -76,6 +86,11 @@ ROBOCO_DEFAULT_EMBEDDING_MODEL=qwen3-embedding:0.6b
 # =============================================================================
 # Security
 # =============================================================================
+# Encryption key for git tokens at rest (Fernet). REQUIRED — the orchestrator
+# refuses to start without it. Generate with:
+#   python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'
+ROBOCO_ENCRYPTION_KEY=
+
 # Agent auth: HMAC secret that signs X-Agent-Token. REQUIRED for docker compose.
 # Generate with: python -c 'import secrets; print(secrets.token_hex(32))'
 ROBOCO_AGENT_AUTH_SECRET=
@@ -107,25 +107,64 @@ roboco/
 │   └── rag/                     # Agent knowledge base (indexed into RAG)
 ├── alembic/                     # Database migrations
 ├── CLAUDE.md                    # Claude Code guidance
-└── docker-compose.yml           # Local development stack
+├── docker-compose.yml           # Full stack, built from source
+└── docker-compose.registry.yml  # Full stack, pulled from the image registry
 ```

-## Quick Start
+## Running RoboCo
+
+You need **Docker** + **Docker Compose** and a Claude Code auth directory on
+the host (`~/.claude`, mounted into the orchestrator so agents can reach the
+model). Copy `.env.example` to `.env` and set at least `ROBOCO_ENCRYPTION_KEY`
+and `ROBOCO_AGENT_AUTH_SECRET` (that file shows how to generate each). However
+you start it, the whole company is reachable at one origin:
+**http://localhost:3000**.
+
+### Option 1 — Run the pre-built images (quickest)
+
+Every release publishes all RoboCo images to both the GitHub Container
+Registry and Docker Hub, so you can run the full stack without building
+anything. Use the registry compose:
+
+```bash
+git clone https://github.com/rennf93/roboco.git && cd roboco
+cp .env.example .env                                   # then edit in your secrets
+docker compose -f docker-compose.registry.yml pull
+docker compose -f docker-compose.registry.yml up -d
+```
+
+Choose the registry and version with two env vars (defaults shown):
+
+```bash
+ROBOCO_REGISTRY=ghcr.io/rennf93   # or docker.io/renzof93
+ROBOCO_VERSION=latest             # or a pinned release, e.g. 0.5.0
+```
+
+The orchestrator spawns the matching pre-built agent images on demand — no
+build toolchain or source compile on your host.
+
+### Option 2 — Build from source
+
+The same full stack, built locally from the Dockerfiles instead of pulled:
+
+```bash
+git clone https://github.com/rennf93/roboco.git && cd roboco
+cp .env.example .env              # then edit in your secrets
+docker compose up -d              # builds images on first run, then starts everything
+```
+
+### Option 3 — Local development (no full stack)
+
+For hacking on the code itself, run only the backing services in Docker and
+the API on your host:

 ```bash
-# Install dependencies
 uv sync
+docker compose up -d postgres redis ollama   # backing services only
+uv run alembic upgrade head                   # migrate the database
+uv run python -m roboco.cli                   # API + orchestrator

-# Start PostgreSQL and Redis (Docker)
-docker compose up -d
-
-# Run database migrations
-uv run alembic upgrade head
-
-# Start the API server
-uv run python -m roboco.cli
-
-# Or just the API without orchestrator
+# Or just the API without the orchestrator:
 uv run uvicorn roboco.api.app:app --reload --host 0.0.0.0 --port 8000
 ```

@@ -17,25 +17,42 @@ claude  # Login via browser

 ## Quick Start (NAS/Server)

-Everything runs in Docker - no need to install Python/uv on the host.
+Everything runs in Docker - no need to install Python/uv on the host. There
+are two ways to get the stack: **pull the pre-built images** (every release
+publishes them) or **build from source**. Both start from a clone, which gives
+you the compose files, the nginx config, and `.env.example`.

 ```bash
 # 1. Clone the project
-git clone <repo-url> roboco
+git clone https://github.com/rennf93/roboco.git roboco
 cd roboco

 # 2. Configure environment
 cp .env.example .env

-# 3. Set host paths for your NAS (IMPORTANT!)
-# Edit .env and set:
-#   ROBOCO_HOST_PROJECT_DIR=/volume1/roboco
-#   ROBOCO_HOST_CLAUDE_DIR=/root/.claude  (or your user's home)
+# 3. Edit .env and set at least:
+#   ROBOCO_ENCRYPTION_KEY, ROBOCO_AGENT_AUTH_SECRET   (secrets; see the file)
+#   ROBOCO_HOST_PROJECT_DIR=/volume1/roboco           (host paths for spawning agents)
+#   ROBOCO_HOST_CLAUDE_DIR=/root/.claude              (or your user's home)
+```

-# 4. Start everything (PostgreSQL + Redis + Orchestrator)
-docker compose up -d
+### Option A — Pull the pre-built images (no build toolchain on the host)

-# 5. View logs
+```bash
+docker compose -f docker-compose.registry.yml pull
+docker compose -f docker-compose.registry.yml up -d
+docker compose -f docker-compose.registry.yml logs -f orchestrator
+```
+
+Choose the registry and version with `ROBOCO_REGISTRY` (`ghcr.io/rennf93` or
+`docker.io/renzof93`) and `ROBOCO_VERSION` (`latest` or a pinned release such
+as `0.5.0`). The orchestrator pulls and spawns the matching pre-built agent
+images on demand.
+
+### Option B — Build from source
+
+```bash
+docker compose up -d              # builds images on first run, then starts everything
 docker compose logs -f orchestrator
 ```

@@ -51,7 +68,7 @@ Your NAS/Server
 │   └── roboco-orchestrator
 │       │
 │       ├── Runs FastAPI on port 8000
-│       ├── Builds roboco-agent image (once)
+│       ├── Builds (from source) or pulls (registry) the agent images
 │       └── Spawns agent containers:
 │           ├── roboco-agent-main-pm
 │           ├── roboco-agent-be-dev-1
@@ -241,10 +241,31 @@ the on-demand Intake and Secretary only run while you're interacting with them.
 Steady-state memory is dominated by the standing services (Postgres, Redis,
 and especially Ollama with its models loaded), not by the agents.

-Storage is the larger footprint: the built (or pulled) image set. The agent
-images all share a common base layer, so on disk they cost far less than their
-nominal sizes added together. `docker system prune` reclaims old image versions
-and stopped agent containers.
+Measured at idle on the reference NAS (full stack up, no task running), the
+standing services use roughly:
+
+| Service | RAM (idle) |
+|---------|------------|
+| Ollama (models loaded) | ~2.2 GB |
+| Orchestrator | ~150 MB |
+| Postgres | ~60 MB |
+| Panel | ~35 MB |
+| Redis | ~15 MB |
+| nginx | ~10 MB |
+
+So the whole standing stack idles around ~2.5 GB, almost all of it Ollama;
+the application itself is a few hundred MB. (These are idle figures — peak
+memory while agents are actively working will be higher, and is best read
+live with `docker stats` while a task is in flight.)
+
+Storage is the larger footprint: the image set. The agent images all build
+`FROM` a shared base layer, so on disk they cost far less than their nominal
+sizes added together. For reference, the panel image is ~230 MB, the
+orchestrator ~0.9 GB, the agent base ~1.1 GB, and each agent image ~1.1 GB
+(the frontend dev/QA images are larger, ~1.9 GB, for their browser/Node
+toolchain) — but the shared base means the real on-disk total is well below
+their sum. `docker system prune` reclaims old image versions, stopped agent
+containers, and build cache (typically a few GB).

 Monitor with:
 ```bash