Docker Setup
Complete Docker Compose configuration for running the Kaizen Core stack.
Quick Start
# From repository root
docker compose up -d
# Check status
docker compose ps
# View logs
docker compose logs -f write-node
# Access services
open http://localhost:3000 # Tester
open http://localhost:3003 # Grafana (admin/kaizen)Architecture
Services
| Service | Port | Description |
|---|---|---|
| write-node | 8545, 9000 | Sequencer (RPC+WS at /ws, gRPC) |
| read-node-aggressive | 8547, 9001 | Low-latency queries |
| read-node-archive | 8548, 9002 | Full history |
| proxy | 8546 | RPC proxy (WS at /ws) |
| oracle | 8550 | Price aggregator |
| bridge | 3002 | Deposit relay |
| solver | 3001 | Quote provider |
| settler | 9091 (metrics) | Settlement service |
| postgres | 5432 | Indexer database |
| tester | 3000 | Frontend app |
| grafana | 3003 | Monitoring |
| prometheus | 9090 | Metrics |
| loki | 3100 | Logs |
Read Node Modes
Aggressive Mode
- Purpose: Low-latency queries for real-time applications
- Pruning: Keeps ~16 minutes of history
- Use case: Trading UI, WebSocket,
simulateTransaction - Disk: Minimal
Archive Mode
- Purpose: Full history for indexing and analytics
- Pruning: Disabled
- Use case: Historical queries, auditing
- Disk: Grows over time
RPC Routing
The proxy routes requests automatically:
| Method Type | Target | Examples |
|---|---|---|
| Write | write-node | kaizen_sendTransaction |
| Read | read-node-aggressive | kaizen_getAccount, kaizen_simulateTransaction |
| WebSocket | read-node-aggressive (via broadcast hub) | All subscriptions |
:::tip Unified Endpoint
Frontend only needs localhost:8546 for both RPC and WebSocket.
:::
WebSocket Broadcast Hub
The proxy uses a broadcast hub architecture for WebSocket connections:
- Single upstream WebSocket connection to read-node (not N connections for N clients)
- Efficient message routing - messages routed only to clients with matching subscriptions
- Automatic reconnection with exponential backoff
- Configurable buffer via
BROADCAST_CAPACITY(default: 4096)
See RPC Proxy for detailed documentation.
Configuration Files
| File | Description |
|---|---|
docker/config/write-node.toml | Sequencer configuration |
docker/config/read-node-aggressive.toml | Aggressive pruning |
docker/config/read-node-archive.toml | Archive mode |
Environment Variables
| Variable | Description | Default |
|---|---|---|
BRIDGE_PRIVATE_KEY | Bridge relayer key | Test key |
SOLVER_PRIVATE_KEY | Solver signer key | Test key |
SETTLER_PRIVATE_KEY | Settler key | Test key |
POSTGRES_USER | Database username | kaizen |
POSTGRES_PASSWORD | Database password | kaizen |
GRAFANA_ADMIN_PASSWORD | Grafana password | kaizen |
Test Accounts (Development Only)
| Service | Address | Role |
|---|---|---|
| Bridge | 0x97e6f3163d327d4af7dA38AA779158d2a67A746D | Relayer |
| Solver | 0x88211b41fdd061279477d7801d0A8A04A78aF6a9 | Quote signer |
Development Commands
# Build specific services
docker compose build write-node oracle proxy
# Rebuild after changes
docker compose build --no-cache <service>
docker compose up -d <service>
# Run without monitoring
docker compose up -d write-node read-node-aggressive oracle mock-bridge mock-solver settler proxy tester
# View specific logs
docker compose logs -f write-node oracleTroubleshooting
Node Won't Start
- Check if ports are in use
- Verify config syntax:
cargo run -- init
Read Nodes Not Syncing
- Check gRPC connectivity to write-node:9000
- Verify
write_node_addrin read node config
Grafana Not Showing Data
- Check Prometheus targets: http://localhost:9090/targets
- Verify datasource configuration
Build Failures
docker builder prune
docker compose build --no-cache