Implementation:Helicone Helicone Docker Compose Setup
| Knowledge Sources | |
|---|---|
| Domains | Local Development, Docker |
| Last Updated | 2026-02-14 00:00 GMT |
Overview
Concrete tool for starting Helicone infrastructure services via Docker Compose, provided by docker/docker-compose.yml and the docker/helicone-compose.sh helper script.
Description
The docker/docker-compose.yml file (469 lines) defines the complete Helicone local stack as a multi-profile Docker Compose application named helicone-self-host. Infrastructure services run by default (no profile required), while application services require specific profile activation. The helicone-compose.sh bash script (138 lines) simplifies profile management by mapping human-friendly profile names to Docker Compose --profile flags.
Usage
Use after environment files are in place. Run from the docker/ directory or use the helper script from the repository root.
Code Reference
Source Location
- Repository: Helicone
- File:
docker/docker-compose.yml(lines 1-469),docker/helicone-compose.sh(lines 1-138)
Signature
# Using the helper script (recommended)
./helicone-compose.sh <profile> <command> [options]
# Using docker compose directly
docker compose --profile <profile> up -d
Import
# Docker and Docker Compose must be installed
# The helper script is at docker/helicone-compose.sh
# The compose file is at docker/docker-compose.yml
# Ensure the script is executable
chmod +x docker/helicone-compose.sh
I/O Contract
Inputs
| Name | Type | Required | Description |
|---|---|---|---|
| profile | string | Yes | One of: infra, helicone, dev, workers, kafka, all
|
| command | string | Yes | Docker Compose command: up, down, restart, logs, ps, build, config
|
| docker/.env | file | No | Environment overrides (loaded automatically by Docker Compose) |
Outputs
| Name | Type | Description |
|---|---|---|
| PostgreSQL | service | Database on port 54388 (container: helicone-postgres-flyway-test) |
| ClickHouse | service | Analytics DB on ports 18123 (HTTP) and 19000 (native) |
| MinIO | service | S3-compatible storage on ports 9000 (API) and 9001 (console) |
| Redis | service | Cache on port 6379 |
| Mailhog | service | SMTP on port 1025, web UI on port 8025 |
| migrations | init container | Runs Flyway (PostgreSQL) and ClickHouse migrations on startup |
Usage Examples
Basic Usage
# Start infrastructure only (databases, storage, cache)
cd docker
./helicone-compose.sh infra up
Full Helicone Stack
# Start everything including Jawn and Web (production builds)
cd docker
./helicone-compose.sh helicone up
Development Mode with Hot Reload
# Start infrastructure + dev services with volume mounts for hot reload
cd docker
./helicone-compose.sh dev up
Direct Docker Compose Usage
# Start specific infrastructure services
cd docker
docker compose up db clickhouse minio minio-setup redis -d
# Start with the include-helicone profile
docker compose --profile include-helicone up -d
Monitoring and Troubleshooting
# View logs for a specific service
cd docker
./helicone-compose.sh helicone logs jawn
# Check running services
./helicone-compose.sh helicone ps
# Stop all services
./helicone-compose.sh helicone down
Service Health Checks
Each infrastructure service defines a health check in docker-compose.yml:
# PostgreSQL
healthcheck:
test: ["CMD-SHELL", "pg_isready -U postgres"]
interval: 5s
# ClickHouse
healthcheck:
test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1"]
interval: 10s
# MinIO
healthcheck:
test: ["CMD", "curl", "-f", "http://localhost:9000/minio/health/live"]
interval: 30s
# Redis
healthcheck:
test: ["CMD", "redis-cli", "ping"]
interval: 10s