Files
skills/public/hanzo-stack.md

8.6 KiB

Hanzo Stack - Full Integrated Development Environment

Category: Hanzo Ecosystem Related Skills: hanzo/hanzo-llm-gateway.md, hanzo/hanzo-cloud.md, hanzo/hanzo-database.md

Overview

Hanzo Stack provides the complete integrated development environment for running all Hanzo services locally. One command to start everything: LLM Gateway, Chat, Console, Cloud, IAM, KMS, PostgreSQL, Redis, MongoDB, MinIO.

NOTE: The stack uses three compose files (production, development, core) and git submodules for all services, allowing each service to track its own repo while being orchestrated together.

Why Hanzo Stack?

  • One-command setup: make dev starts everything
  • Three compose profiles: Production, development (hot-reload), core (minimal)
  • Git submodules: Each service tracks its own repo
  • Full ecosystem: All Hanzo services running locally
  • Hot-reload: Development mode with file watching
  • Consistent: Same compose config for all developers
  • Offline-capable: Local models via LLM Gateway + Ollama

When to use

  • Local development across multiple Hanzo services
  • Testing integrations between Hanzo components
  • Full-stack AI application development
  • Onboarding new team members
  • Reproducing production issues locally

Hard requirements

  1. Docker with compose v2
  2. 16GB+ RAM (recommended for full stack)
  3. make (standard on macOS/Linux)

Quick reference

Item Value
Repo github.com/hanzoai (experiments/stack directory)
Setup make setup
Start prod make up
Start dev make dev
Start core make core
Status make status
Stop make down
Logs make logs

Three Compose Files

File Purpose Services
compose.yml Production — optimized, no hot-reload All services, release images
compose.dev.yml Development — hot-reload, source mounts All services, volume mounts
compose.core.yml Core — minimal set for quick start LLM Gateway, Chat, PostgreSQL, Redis
# Production mode
make up # Uses compose.yml

# Development mode (hot-reload)
make dev # Uses compose.yml + compose.dev.yml override

# Core only (minimal, fast startup)
make core # Uses compose.core.yml

Git Submodules

Each service is a git submodule tracking its own repo:

experiments/stack/
├── services/
│ ├── llm/ → github.com/hanzoai/llm (LLM Gateway)
│ ├── chat/ → github.com/hanzoai/chat (Chat UI)
│ ├── console/ → github.com/hanzoai/console (Console)
│ ├── cloud/ → github.com/hanzoai/cloud (Cloud Dashboard)
│ ├── search/ → github.com/hanzoai/search (Search)
│ ├── commerce/ → github.com/hanzoai/commerce (Commerce API)
│ └── ...
├── compose.yml # Production compose
├── compose.dev.yml # Development overrides
├── compose.core.yml # Minimal core services
├── .env.example # Environment template
├── Makefile # All commands
└── README.md
# Initialize submodules
git submodule update --init --recursive

# Update all submodules to latest
git submodule update --remote

# Update specific service
cd services/chat && git pull origin main

Service Ports

Service Port URL Description
Search UI 3000 http://localhost:3000 AI-powered search
Chat UI 3081 http://localhost:3081 Hanzo Chat
LLM Gateway 4000 http://localhost:4000 Unified LLM proxy
Payment API 4242 http://localhost:4242 Commerce API
Admin UI 5173 http://localhost:5173 Admin dashboard
Core API 8000 http://localhost:8000 Main API server
PostgreSQL 5432 postgresql://localhost:5432 Primary database
Redis 6379 redis://localhost:6379 Cache/queues
MongoDB 27017 mongodb://localhost:27017 Document storage
MinIO 9000 http://localhost:9000 S3-compatible storage
Prometheus 9090 http://localhost:9090 Metrics collection

One-file quickstart

# Clone and setup
git clone --recurse-submodules https://github.com/hanzoai/experiments.git
cd experiments/stack

# Configure environment
make setup # Creates .env from .env.example, prompts for API keys

# Start all services (pick one)
make core # Minimal: LLM + Chat + Postgres + Redis
make dev # Full stack with hot-reload
make up # Full stack, production mode

# Verify
make status # Check all services are healthy
curl http://localhost:4000/v1/models # List available models
curl http://localhost:3081 # Open Chat UI

Makefile Commands

make setup # Initial setup (env, pull images, init submodules)
make up # Start all services (production mode)
make dev # Start with hot-reload (development)
make core # Start minimal core services only
make down # Stop all services
make restart # Restart all services
make status # Show service status and health
make logs # Stream all logs
make logs-llm # Stream LLM Gateway logs only
make logs-chat # Stream Chat logs only
make clean # Remove volumes and data
make pull # Pull latest images
make build # Build local images
make test # Run integration tests
make reset # Full reset (clean + setup)
make update # Update all git submodules

Environment Configuration

# .env (created by make setup)

# Required: At least one LLM provider
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
HANZO_API_KEY=hanzo-...

# Optional: Local models
OLLAMA_URL=http://host.docker.internal:11434

# Database
DATABASE_URL=postgresql://hanzo:hanzo@postgres:5432/hanzo
REDIS_URL=redis://redis:6379

# IAM
IAM_ENDPOINT=https://hanzo.id
IAM_CLIENT_ID=app-hanzo
IAM_CLIENT_SECRET=secret

# KMS
KMS_ENDPOINT=https://kms.hanzo.ai
KMS_CLIENT_ID=...
KMS_CLIENT_SECRET=...

Compose Architecture

┌─────────────────────────────────────────┐
│ compose.yml + compose.dev.yml │
├─────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌──────────┐ ┌───────┐ │
│ │ Chat UI │ │ Search │ │ Admin │ │
│ │ :3081 │ │ :3000 │ │ :5173 │ │
│ └────┬─────┘ └────┬─────┘ └───┬───┘ │
│ │ │ │ │
│ ┌────┴──────────────┴────────────┴───┐ │
│ │ LLM Gateway :4000 │ │
│ └────────────────┬───────────────────┘ │
│ │ │
│ ┌────────────────┴───────────────────┐ │
│ │ Core API :8000 │ │
│ └──┬─────────┬──────────┬───────────┘ │
│ │ │ │ │
│ ┌──┴───┐ ┌──┴───┐ ┌───┴────┐ ┌─────┐│
│ │Postgres│ │Redis │ │MongoDB │ │MinIO││
│ │ :5432 │ │:6379 │ │ :27017 │ │:9000││
│ └───────┘ └──────┘ └────────┘ └─────┘│
└─────────────────────────────────────────┘

Troubleshooting

Issue Cause Solution
Port conflict Service already running lsof -i :PORT && kill PID
OOM Too many services Use make core for minimal stack
Slow start Image pull make pull beforehand
DB connection fail Postgres not ready Wait or make restart
Chat not loading Missing OPENAI_API_KEY Add at least one LLM key to .env
Submodule empty Not initialized git submodule update --init --recursive
# Debug specific service
docker compose logs -f llm-gateway
docker compose exec postgres psql -U hanzo

# Reset everything
make clean && make setup && make dev

# Port conflicts
lsof -i :4000 # Find what's using the port
  • hanzo/hanzo-llm-gateway.md - LLM proxy (port 4000)
  • hanzo/hanzo-chat.md - Chat UI (port 3081)
  • hanzo/hanzo-database.md - PostgreSQL/Redis setup
  • hanzo/hanzo-o11y.md - Monitoring (Prometheus port 9090)
  • hanzo/hanzo-universe.md - Production K8s (vs local stack)

Last Updated: 2026-03-13 Category: Hanzo Ecosystem Related: stack, development, local, docker, compose, submodules Prerequisites: Docker, make, 16GB+ RAM