mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
8.6 KiB
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 devstarts 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
- Docker with compose v2
- 16GB+ RAM (recommended for full stack)
- 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
Related Skills
hanzo/hanzo-llm-gateway.md- LLM proxy (port 4000)hanzo/hanzo-chat.md- Chat UI (port 3081)hanzo/hanzo-database.md- PostgreSQL/Redis setuphanzo/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