Deployment

Prerequisites

• Docker and Docker Compose v2+
• 4 GB+ RAM (8 GB recommended for the 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

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

Architecture Overview

┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│  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

Production Deployment

Controller (Django)

gunicorn config.wsgi:application \
  --bind 0.0.0.0:8000 \
  --workers 4 \
  --timeout 120

python manage.py migrate
python manage.py collectstatic --noinput

Required in production

Set DJANGO_SECRET_KEY to a strong random value. Never run with the default.

Dispatcher (Go)

cd dispatcher && go build -o api ./cmd/api

RUNTIME_BACKEND=local \
CONTROLLER_URL=https://controller.internal \
NUM_CONSUMERS=5 \
./api

Infrastructure (AWS)

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

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

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.

See Scaling for detailed configuration.