Principle:Helicone Helicone Infrastructure Services
| Knowledge Sources | |
|---|---|
| Domains | Local Development, Infrastructure |
| Last Updated | 2026-02-14 00:00 GMT |
Overview
Infrastructure services are the stateful backing services (databases, object storage, caches, email) that Helicone application services depend on, all orchestrated locally via Docker Compose.
Description
The Helicone platform requires several infrastructure services to function:
- PostgreSQL (postgres:17.4): Primary relational database for application data, users, organizations, and API keys. Exposed on port 54388.
- ClickHouse (clickhouse-server:24.3.13.40): Column-oriented analytics database for request/response logs and metrics. Exposes HTTP on port 18123 and native protocol on port 19000.
- MinIO: S3-compatible object storage for request/response body payloads. API on port 9000, console on port 9001. Automatically creates buckets
request-response-storage,prompt-body-storage, andhql-storevia theminio-setupinit container. - Redis (redis:8.0.2-alpine): In-memory cache and queue backend. Exposed on port 6379.
- Mailhog: SMTP testing server that captures outbound emails. SMTP on port 1025, web UI on port 8025.
A migrations service runs automatically after PostgreSQL and ClickHouse are healthy, applying Flyway migrations for PostgreSQL and ClickHouse schema migrations.
The Docker Compose file defines multiple profiles to control which services start:
| Profile | Services Included |
|---|---|
| (default/infra) | db, clickhouse, minio, minio-setup, mailhog, redis, migrations |
| include-helicone | Infrastructure + jawn + web (production builds) |
| dev | Infrastructure + jawn-dev + web-dev (hot reload) |
| workers | Infrastructure + worker proxies (OpenAI, Anthropic, Gateway, Helicone API, Generate) |
| kafka | Infrastructure + Zookeeper + Kafka (experimental) |
Usage
Use this principle after environment configuration is complete. Start the infrastructure stack before running any application services or database migrations.
Theoretical Basis
Docker Compose profiles allow a single compose file to define the entire system while letting developers start only the subset they need. Health checks with condition: service_healthy ensure services start in the correct order -- migrations only run after databases are ready, and application services only start after migrations complete. This dependency graph prevents race conditions during startup.
The helicone-compose.sh helper script wraps Docker Compose with a friendly CLI, mapping profile names like helicone, dev, and infra to the correct --profile flags.