Environment:Helicone Helicone Docker Compose Infrastructure

Knowledge Sources	Helicone Monorepo Docker Compose
Domains	Infrastructure, Local_Development
Last Updated	2026-02-14 06:00 GMT

Overview

Docker Compose stack providing PostgreSQL 17.4, ClickHouse 24.3, Redis 8.0, MinIO, and optional Kafka for local Helicone development.

Description

This environment orchestrates all infrastructure services required to run Helicone locally. The stack uses named Docker Compose profiles to separate infrastructure services (always running) from application services (optional). It includes PostgreSQL for application data, ClickHouse for analytics, Redis for caching/queuing, MinIO for S3-compatible object storage, and optionally Kafka for message queuing. Flyway handles PostgreSQL schema migrations, and a custom Python script manages ClickHouse migrations.

Usage

Use this environment for local development and integration testing. It is the mandatory prerequisite for running the Helicone web dashboard, Jawn backend, and end-to-end tests locally. Start it via `./helicone-compose.sh helicone up`.

System Requirements

Category	Requirement	Notes
OS	Linux or macOS	Docker Desktop required on macOS/Windows
Docker	Docker Engine 24+	With Docker Compose v2
RAM	8GB minimum	ClickHouse and PostgreSQL are memory-intensive
Disk	10GB+ SSD	For database volumes and container images
Ports	54388, 18123, 19000, 9000, 9001, 6379, 8585	Must be available on localhost

Dependencies

Container Images

`postgres:17.4` (PostgreSQL database)
`clickhouse/clickhouse-server:24.3.13.40` (Analytics database)
`redis:8.0.2-alpine` (Cache and message queue)
`minio/minio` (S3-compatible object storage)
`minio/mc:RELEASE.2025-04-08T15-39-49Z` (MinIO client for bucket setup)
`mailhog/mailhog` (Local email testing)
`ubuntu:20.04` (Migration runner base)

Optional Container Images (Kafka profile)

`confluentinc/cp-zookeeper:7.8.0`
`confluentinc/cp-kafka:7.8.0`

Migration Tools

Flyway 10.5.0 (PostgreSQL migrations, requires OpenJDK 17 JRE)
Python 3.12 with `tabulate` >= 0.9.0 and `yarl` >= 1.15.2 (ClickHouse migrations)

Credentials

Default local development credentials (not for production):

`POSTGRES_USER`: `postgres`
`POSTGRES_PASSWORD`: `testpassword`
`POSTGRES_DB`: `helicone_test`
`CLICKHOUSE_DEFAULT_USER`: `default` (no password)
`MINIO_ROOT_USER`: `minioadmin`
`MINIO_ROOT_PASSWORD`: `minioadmin`
`REDIS_PASSWORD`: `helicone-redis-pw`

Quick Install

# Start all infrastructure services
./helicone-compose.sh helicone up

# Or start specific services
docker compose up db clickhouse minio redis -d

# Run database migrations
docker compose run --rm clickhouse-migration-runner

Code Evidence

PostgreSQL service from `docker/docker-compose.yml:8-23`:

db:
  image: postgres:17.4
  container_name: helicone-postgres-flyway-test
  environment:
    POSTGRES_DB: helicone_test
    POSTGRES_USER: postgres
    POSTGRES_PASSWORD: testpassword
  ports:
    - "54388:5432"
  healthcheck:
    test: ["CMD-SHELL", "pg_isready -U postgres"]
    interval: 5s
    timeout: 5s
    retries: 5

ClickHouse service from `docker/docker-compose.yml:25-49`:

clickhouse:
  image: clickhouse/clickhouse-server:24.3.13.40
  container_name: helicone-clickhouse
  ports:
    - "18123:8123"
    - "19000:9000"
  ulimits:
    nofile:
      soft: 262144
      hard: 262144
  healthcheck:
    test: ["CMD-SHELL", "wget --no-verbose --tries=1 --spider http://localhost:8123/ping || exit 1"]
    interval: 10s
    timeout: 5s
    retries: 5
    start_period: 30s

MinIO bucket initialization from `docker/docker-compose.yml:70-80`:

/usr/bin/mc alias set localminio http://minio:9000 minioadmin minioadmin;
/usr/bin/mc mb --ignore-existing localminio/request-response-storage;
/usr/bin/mc mb --ignore-existing localminio/prompt-body-storage;
/usr/bin/mc mb --ignore-existing localminio/hql-store;

Common Errors

Error Message	Cause	Solution
`port is already allocated`	Another service using required port	Stop conflicting services or change port mappings
`clickhouse healthcheck: unhealthy`	ClickHouse needs `start_period` to initialize	Wait 30 seconds for ClickHouse startup; check `ulimits` settings
`no matching manifest for linux/arm64`	Apple Silicon M-series Mac	Use `--platform linux/amd64` or check for ARM-compatible images
`minio-setup exited with code 1`	MinIO not yet healthy when setup runs	Ensure MinIO healthcheck passes before setup runs (depends_on condition)

Compatibility Notes

ClickHouse ulimits: The `nofile` ulimit must be set to 262144 (both soft and hard). Without this, ClickHouse may fail to start with "too many open files" errors.
Port mappings: Non-standard external ports are used (54388 for PostgreSQL, 18123 for ClickHouse HTTP) to avoid conflicts with locally-installed databases.
MinIO buckets: Three buckets are auto-created: `request-response-storage`, `prompt-body-storage`, and `hql-store`. These must exist before the application can store/retrieve data.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment