mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Renn F
46c1ab8af2
- CLAUDE.md + README.md: RAG engine is hybrid retrieval, not HyDE (retired) - usage.md: org chart + agent-IDs table now show all 22 agents (adds secretary-1 + pr-reviewer-1); task-lifecycle diagram adds awaiting_pm_review and the awaiting_ceo_approval escalation - deployment.md: architecture diagram + data-persistence table include ollama, panel, nginx, workspaces, and logs - docs/initiatives + docs/self READMEs: access lists match middleware_docs.py - CLAUDE.md blueprint pointer no longer references the gitignored docs/internal tree
236 lines
6.1 KiB
Markdown
236 lines
6.1 KiB
Markdown
# RoboCo Deployment Guide
|
|
|
|
Deploy RoboCo on your server/NAS.
|
|
|
|
## Prerequisites
|
|
|
|
| Software | Purpose |
|
|
|----------|---------|
|
|
| Docker | All services (PostgreSQL, Redis, Orchestrator, Agents) |
|
|
| Claude Code CLI | Authenticate once on host (creates ~/.claude) |
|
|
|
|
```bash
|
|
# Install and authenticate Claude Code (one time)
|
|
npm install -g @anthropic-ai/claude-code
|
|
claude # Login via browser
|
|
```
|
|
|
|
## Quick Start (NAS/Server)
|
|
|
|
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 https://github.com/rennf93/roboco.git roboco
|
|
cd roboco
|
|
|
|
# 2. Configure environment
|
|
cp .env.example .env
|
|
|
|
# 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)
|
|
```
|
|
|
|
### Option A — Pull the pre-built images (no build toolchain on the host)
|
|
|
|
```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
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
Your NAS/Server
|
|
│
|
|
├── docker compose up -d
|
|
│ │
|
|
│ ├── roboco-postgres (pgvector)
|
|
│ ├── roboco-redis
|
|
│ ├── roboco-ollama (+ ollama-init: pulls the embedding + local LLM models)
|
|
│ ├── roboco-orchestrator
|
|
│ │ │
|
|
│ │ ├── Runs FastAPI on port 8000
|
|
│ │ ├── Builds (from source) or pulls (registry) the agent images
|
|
│ │ └── Spawns agent containers:
|
|
│ │ ├── roboco-agent-main-pm
|
|
│ │ ├── roboco-agent-be-dev-1
|
|
│ │ ├── roboco-agent-be-qa
|
|
│ │ └── ... (each mounts ~/.claude for auth)
|
|
│ ├── roboco-panel (Next.js control panel, internal)
|
|
│ └── roboco-nginx (single entry point on :3000 → panel + /api,/ws → orchestrator)
|
|
│
|
|
├── ~/.claude/ ← Your Claude Code auth (from host)
|
|
│
|
|
└── ./data/ ← Persistent data
|
|
├── postgres/
|
|
├── redis/
|
|
├── ollama/ ← model cache (multi-GB)
|
|
├── workspaces/ ← per-agent git clones
|
|
├── logs/
|
|
└── mcp-configs/
|
|
```
|
|
|
|
## Configuration
|
|
|
|
### Environment Variables (.env)
|
|
|
|
```bash
|
|
# Host paths - REQUIRED for NAS deployment
|
|
# These tell the orchestrator where to find files on the HOST
|
|
ROBOCO_HOST_PROJECT_DIR=/volume1/roboco
|
|
ROBOCO_HOST_CLAUDE_DIR=/root/.claude
|
|
ROBOCO_DATA_DIR=./data
|
|
|
|
# Claude Code auth directory (mounted into containers)
|
|
CLAUDE_AUTH_DIR=/root/.claude
|
|
|
|
# Database (defaults work for docker compose)
|
|
ROBOCO_DATABASE_HOST=roboco-postgres
|
|
ROBOCO_DATABASE_PORT=5432
|
|
ROBOCO_DATABASE_USER=roboco
|
|
ROBOCO_DATABASE_PASSWORD=roboco
|
|
ROBOCO_DATABASE_NAME=roboco
|
|
|
|
# Redis (defaults work for docker compose)
|
|
ROBOCO_REDIS_HOST=roboco-redis
|
|
ROBOCO_REDIS_PORT=6379
|
|
```
|
|
|
|
### Customizing Agent Spawn
|
|
|
|
By default, the orchestrator spawns `main-pm`, `be-dev-1`, and `be-qa`. To change this:
|
|
|
|
```bash
|
|
# Option 1: Override in docker-compose.yml
|
|
docker compose up -d --scale orchestrator=0
|
|
docker compose run orchestrator --spawn main-pm fe-dev-1 fe-qa
|
|
|
|
# Option 2: Edit docker-compose.yml command section
|
|
# Uncomment and modify the command line
|
|
```
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
# API health
|
|
curl http://localhost:8000/health
|
|
|
|
# Orchestrator status (shows running containers)
|
|
curl http://localhost:8000/api/orchestrator/status | jq
|
|
|
|
# List all RoboCo containers
|
|
docker ps --filter "name=roboco"
|
|
|
|
# View orchestrator logs
|
|
docker compose logs -f orchestrator
|
|
|
|
# View agent logs
|
|
docker logs -f roboco-agent-main-pm
|
|
```
|
|
|
|
## Data Persistence
|
|
|
|
All data is persisted to the host:
|
|
|
|
| Container Path | Host Path |
|
|
|----------------|-----------|
|
|
| postgres data | `./data/postgres/` |
|
|
| redis data | `./data/redis/` |
|
|
| Ollama models | `./data/ollama/` |
|
|
| Agent workspaces | `./data/workspaces/` |
|
|
| Agent + orchestrator logs | `./data/logs/` |
|
|
| MCP configs | `./data/mcp-configs/` |
|
|
|
|
For NAS RAID protection, set `ROBOCO_DATA_DIR` to your RAID volume:
|
|
|
|
```bash
|
|
ROBOCO_DATA_DIR=/volume1/roboco/data
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Orchestrator can't spawn agents
|
|
|
|
```bash
|
|
# Check Docker socket is mounted
|
|
docker compose logs orchestrator | grep -i docker
|
|
|
|
# Verify host paths are set correctly
|
|
docker compose exec orchestrator env | grep ROBOCO_HOST
|
|
|
|
# Check if agent image was built
|
|
docker images | grep roboco-agent
|
|
```
|
|
|
|
### Agent containers exit immediately
|
|
|
|
```bash
|
|
# Check Claude auth is mounted
|
|
docker logs roboco-agent-main-pm
|
|
|
|
# Verify ~/.claude exists on host
|
|
ls -la ~/.claude/
|
|
|
|
# Re-authenticate if needed
|
|
claude
|
|
```
|
|
|
|
### Database connection failed
|
|
|
|
```bash
|
|
docker compose ps postgres
|
|
docker compose logs postgres
|
|
```
|
|
|
|
### API not responding
|
|
|
|
```bash
|
|
curl http://localhost:8000/health
|
|
docker compose logs orchestrator
|
|
```
|
|
|
|
## Stopping
|
|
|
|
```bash
|
|
# Stop all services
|
|
docker compose down
|
|
|
|
# Stop all agent containers (if needed)
|
|
docker ps --filter "name=roboco-agent" -q | xargs docker stop
|
|
|
|
# Full cleanup (removes volumes)
|
|
docker compose down -v
|
|
```
|
|
|
|
## Development Mode (Host)
|
|
|
|
For local development without Docker orchestrator:
|
|
|
|
```bash
|
|
# Start only infrastructure
|
|
docker compose up -d postgres redis
|
|
|
|
# Install Python dependencies
|
|
curl -LsSf https://astral.sh/uv/install.sh | sh
|
|
uv sync
|
|
|
|
# Run migrations
|
|
uv run alembic upgrade head
|
|
|
|
# Start orchestrator directly
|
|
uv run python -m roboco.cli --spawn main-pm be-dev-1 be-qa
|
|
```
|