Skip to content

Operator Deployment Guide

Prerequisites

  • Docker and Docker Compose v2+
  • 4GB+ RAM (8GB recommended for full stack with Temporal)
  • Ports: 8000 (Controller), 8080 (Dispatcher), 9000/9001 (MinIO), 7233 (Temporal), 8088 (Temporal UI)

Quick Start

git clone git@github.com:ConflictHQ/kohakku.git
cd kohakku
make setup   # creates .env files from examples
make up      # starts all services
make migrate # runs Django migrations
make seed    # seeds demo data

Controller: http://localhost:8000 Dispatcher: http://localhost:8080 Temporal UI: http://localhost:8088 MinIO Console: http://localhost:9001 (minioadmin/minioadmin)

Architecture

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  Controller │────▶│  Dispatcher  │────▶│   Agents    │
│  (Django)   │     │  (Go + Chi)  │     │  (Docker)   │
└──────┬──────┘     └──────┬───────┘     └─────────────┘
       │                   │
  ┌────┴────┐         ┌────┴────┐
  │Postgres │         │  Redis  │
  │ + MinIO │         │         │
  └─────────┘         └─────────┘
       │
  ┌────┴────┐
  │Temporal │
  └─────────┘

Services

Service Port Purpose
controller 8000 Django app — task management, workflow orchestration, operator UI
dispatcher 8080 Go service — queue consumer, container spawning, agent protocol
temporal-worker — Python process — runs Temporal workflows and activities
celery-worker — Task queue — brief lifecycle, health checks, failure reports
celery-beat — Periodic scheduler — cron-like task scheduling
postgres 5432 Shared database (separate DBs for Controller and Dispatcher)
redis 6379 Cache, task queue, Celery broker
minio 9000 Object storage for briefs and skill packages
temporal 7233 Workflow orchestration engine

Environment Variables

Controller

Variable Default Description
DJANGO_SECRET_KEY — Required in production
DJANGO_DEBUG false Enable debug mode
DJANGO_ALLOWED_HOSTS localhost Comma-separated allowed hosts
POSTGRES_HOST postgres Database host
REDIS_URL redis://localhost:6379/1 Redis for cache and sessions
CONTROLLER_URL http://localhost:8000 Self URL for callback URLs
AGENT_IMAGE_REGISTRY localhost:5000/kohakku-agents Container registry for agent images
CALLBACK_SIGNING_KEY — HMAC key for callback verification
TEMPORAL_ADDRESS localhost:7233 Temporal server address

Dispatcher

Variable Default Description
CONTROLLER_URL http://localhost:8000 Controller API endpoint
RUNTIME_BACKEND local Runtime: local, worker
NUM_CONSUMERS 3 Parallel consumer goroutines
MAX_CONCURRENT_PULLS 2 Concurrent image pull limit
QUEUE_SOURCE internal Queue: internal, redis-stream
DISPATCHER_NAME default Identity for Controller registration
DOCKER_NETWORK kohakku_default Docker network for agent containers

Production Deployment

Controller (Django)

# Use gunicorn with multiple workers
gunicorn config.wsgi:application \
  --bind 0.0.0.0:8000 \
  --workers 4 \
  --timeout 120

# Run migrations
python manage.py migrate
python manage.py collectstatic --noinput

Dispatcher (Go)

# Build the binary
cd dispatcher && go build -o api ./cmd/api

# Run with production config
RUNTIME_BACKEND=local \
CONTROLLER_URL=https://controller.internal \
NUM_CONSUMERS=5 \
./api

Scaling

  • Controller: Horizontal — run multiple instances behind a load balancer. Stateless except for DB sessions.
  • Dispatcher: Horizontal — run multiple instances. Each registers with Controller independently. Use redis-stream queue source for fan-out.
  • Temporal Worker: Horizontal — multiple workers on the same task queue.
  • Celery Workers: Horizontal — add more workers for throughput.

Infrastructure (AWS)

Use the Terraform modules in terraform/ecs/ and terraform/gke/ to bootstrap the agent runtime infrastructure.

cd terraform/ecs
terraform init
terraform plan -var="vpc_id=vpc-xxx" -var="private_subnet_ids=[\"subnet-a\",\"subnet-b\"]"
terraform apply

Monitoring

  • Controller health: GET /health/ (JSON, checks DB)
  • Controller readiness: GET /ready/ (checks DB + Redis + MinIO)
  • Dispatcher health: GET /health (JSON)
  • Temporal UI: http://localhost:8088 (workflow execution visibility)
  • MinIO Console: http://localhost:9001 (object storage)

Backup

  • Postgres: Use pg_dump or managed database snapshots
  • MinIO: Sync bucket to S3 with mc mirror
  • Redis: RDB snapshots (non-critical — reconstructible from DB)