Self-Hosting
Deploy Brokle on your infrastructure with Docker, Docker Compose, or Kubernetes - complete data control and privacy compliance
Self-Hosting
Deploy Brokle on your own infrastructure for complete control over your data and customization options.
Why Self-Host?
- Data Privacy: Keep all traces and data within your infrastructure
- Compliance: Meet your organization's regulatory requirements with full infrastructure control
- Customization: Modify and extend Brokle for your needs
- Cost Control: Predictable infrastructure costs at scale
- Network Isolation: Run in air-gapped or private networks
Deployment Options
Docker
Single-server deployment with Docker
Docker Compose
Multi-container deployment for development and small teams
Kubernetes
Production-grade deployment with Kubernetes
Configuration
Environment variables and configuration options
Architecture Overview
Brokle consists of several components:
┌─────────────────────────────────────────────────────────────────┐
│ Brokle Architecture │
├─────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Web UI │ │ API Server │ │ Worker │ │
│ │ (Next.js) │────▶│ (Go) │ │ (Go) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────────────────────────────────────────────────┐│
│ │ Redis Streams ││
│ └──────────────────────────────────────────────────────────┘│
│ │ │
│ ┌─────────────────────┼─────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ PostgreSQL │ │ ClickHouse │ │ Redis │ │
│ │ (Metadata) │ │ (Analytics) │ │ (Cache) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘Components
| Component | Purpose | Port |
|---|---|---|
| API Server | HTTP API, authentication, routing | 8080 |
| Worker | Background processing, telemetry ingestion | - |
| Web UI | Dashboard interface | 3000 |
| PostgreSQL | Transactional data, users, projects | 5432 |
| ClickHouse | Analytics, traces, high-volume data | 8123/9000 |
| Redis | Cache, queues, pub/sub | 6379 |
System Requirements
Minimum (Development/Small Teams)
| Resource | Requirement |
|---|---|
| CPU | 4 cores |
| RAM | 8 GB |
| Storage | 50 GB SSD |
| Network | 100 Mbps |
Recommended (Production)
| Resource | Requirement |
|---|---|
| CPU | 8+ cores |
| RAM | 32+ GB |
| Storage | 500 GB+ SSD |
| Network | 1 Gbps |
Storage requirements depend heavily on trace volume. Plan for approximately 1 KB per trace average.
Quick Start
The fastest way to get started is with Docker Compose:
# Clone the repository
git clone https://github.com/brokle-ai/brokle.git
cd brokle
# Start all services
docker compose up -d
# Access the dashboard
open http://localhost:3000See the Docker Compose guide for detailed instructions.
Database Setup
PostgreSQL
PostgreSQL stores transactional data:
- Users and authentication
- Organizations and projects
- API keys and settings
- Prompt versions
# Create database
createdb brokle
# Run migrations
./brokle migrate upClickHouse
ClickHouse stores high-volume analytics data:
- Traces and spans
- Metrics and events
- Cost data
# ClickHouse migrations run automatically on startup
# Or run manually:
./brokle migrate up --db clickhouseRedis
Redis handles:
- Session caching
- Rate limiting
- Background job queues
- Real-time updates
Security Considerations
Network Security
- Run behind a reverse proxy (nginx, Traefik)
- Use TLS/SSL for all connections
- Restrict database access to internal networks
- Use firewall rules to limit exposure
Authentication
- Configure strong JWT secrets
- Enable rate limiting
- Set up SSO for enterprise (SAML, OIDC)
- Use API key rotation policies
Data Security
- Encrypt data at rest
- Use encrypted connections to databases
- Implement backup strategies
- Configure retention policies
Monitoring
Brokle exposes metrics for monitoring:
# Prometheus metrics
/metrics # Application metrics
/health # Health check endpoint
/ready # Readiness probeKey Metrics
| Metric | Description |
|---|---|
brokle_traces_total | Total traces ingested |
brokle_api_requests_total | API request count |
brokle_api_latency_seconds | API response latency |
brokle_worker_queue_size | Worker queue depth |
Upgrading
# Pull latest images
docker compose pull
# Restart with new version
docker compose up -d
# Run migrations
docker compose exec server ./brokle migrate upAlways backup your databases before upgrading. Check the changelog for breaking changes.
Support
For self-hosting support:
- GitHub Issues - Bug reports and feature requests
- GitHub Discussions - Questions and community support
- Discord - Real-time community chat
Next Steps
- Docker Deployment - Simple single-node setup
- Configuration Reference - All configuration options
- Kubernetes - Production deployment