Docker - Helicone OSS LLM Observability

To run all services in a single Docker container, you can use the helicone-all-in-one image.

Quick Start (Local)

Get Docker and run the container:

docker pull helicone/helicone-all-in-one:latest
docker run -d \
  --name helicone \
  -p 3000:3000 \
  -p 8585:8585 \
  -p 9080:9080 \
  helicone/helicone-all-in-one:latest

Access the dashboard at http://localhost:3000.

Example to test the Jawn service

curl --location 'http://localhost:8585/v1/gateway/oai/v1/chat/completions' \
--header "Content-Type: application/json" \
--header "Authorization: Bearer $OPENAI_API_KEY" \
--header "Helicone-Auth: Bearer $HELICONE_API_KEY" \
--data '{
    "model": "gpt-4o-mini",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Production Setup (Remote Server)

When deploying to a remote server (EC2, VPS, etc.), configure your server’s public IP or domain:

# Replace YOUR_IP with your server's public IP or domain
export PUBLIC_URL="http://YOUR_IP:3000"
export JAWN_URL="http://YOUR_IP:8585"
export S3_URL="http://YOUR_IP:9080"

docker run -d \
  --name helicone \
  -p 3000:3000 \
  -p 8585:8585 \
  -p 9080:9080 \
  -e SITE_URL="$PUBLIC_URL" \
  -e BETTER_AUTH_URL="$PUBLIC_URL" \
  -e BETTER_AUTH_SECRET="$(openssl rand -base64 32)" \
  -e NEXT_PUBLIC_APP_URL="$PUBLIC_URL" \
  -e NEXT_PUBLIC_HELICONE_JAWN_SERVICE="$JAWN_URL" \
  -e NEXT_PUBLIC_IS_ON_PREM=true \
  -e S3_ENDPOINT="$S3_URL" \
  helicone/helicone-all-in-one:latest

Environment Variables

The container uses these environment variables (with defaults for local development):

Variable	Default	Description
`NEXT_PUBLIC_HELICONE_JAWN_SERVICE`	`http://localhost:8585`	URL browsers use to reach the API. Must be public URL for remote deployments.
`S3_ENDPOINT`	`http://localhost:9080`	URL browsers use for presigned URLs. Must be public URL for remote deployments.
`S3_ACCESS_KEY`	`minioadmin`	MinIO access key
`S3_SECRET_KEY`	`minioadmin`	MinIO secret key
`S3_BUCKET_NAME`	`request-response-storage`	S3 bucket for request/response bodies
`BETTER_AUTH_SECRET`	`change-me-in-production`	Auth secret. Generate a secure value for production.
`SITE_URL`	-	Public URL of the web dashboard
`BETTER_AUTH_URL`	-	Same as SITE_URL
`NEXT_PUBLIC_APP_URL`	-	Same as SITE_URL
`NEXT_PUBLIC_IS_ON_PREM`	-	Set to `true` for non-localhost deployments

Port Requirements

Port	Service	Required For
3000	Web Dashboard	Browser access
8585	Jawn API + LLM Proxy	Browser API calls, LLM proxying
9080	MinIO S3	Request/response body storage
5432	PostgreSQL	Internal (can be restricted)
8123	ClickHouse	Internal (can be restricted)

Important: Ports 3000, 8585, and 9080 must be accessible from browsers accessing the dashboard.

User Account Setup

Create Account

Navigate to http://YOUR_IP:3000/signup and create your account.

Email Verification

The container doesn’t include email services. Manually verify users:

docker exec -u postgres helicone psql -d helicone_test -c \
  "UPDATE \"user\" SET \"emailVerified\" = true WHERE email = 'your@email.com';"

Organization Setup

Users need an organization. If you see “No organization ID found” errors:

# Get your user ID
docker exec -u postgres helicone psql -d helicone_test -c \
  "SELECT id, email FROM \"user\" WHERE email = 'your@email.com';"

# Create organization (save the returned ID)
docker exec -u postgres helicone psql -d helicone_test -c \
  "INSERT INTO organization (name, is_personal) VALUES ('My Org', true) RETURNING id;"

# Add user to organization (replace USER_ID and ORG_ID)
docker exec -u postgres helicone psql -d helicone_test -c \
  "INSERT INTO organization_member (\"user\", organization, org_role) \
   VALUES ('USER_ID', 'ORG_ID', 'admin');"

Supported LLM Providers

OpenAI: http://YOUR_IP:8585/v1/gateway/oai/v1/chat/completions
Anthropic: http://YOUR_IP:8585/v1/gateway/anthropic/v1/messages

Other providers (Vertex AI, AWS Bedrock, Azure OpenAI) are not supported in the self-hosted version.

Important Notes

Data Persistence

Container restarts will wipe all data. For production, mount Docker volumes:

-v helicone-postgres:/var/lib/postgresql/data \
-v helicone-clickhouse:/var/lib/clickhouse \
-v helicone-minio:/data

Security

Port 8585 does not require authentication for proxying requests. Anyone with access can proxy LLM requests through your endpoint. Restrict access via firewall rules.

HTTPS

For HTTPS support, use a reverse proxy (Caddy, nginx, Traefik) in front of the container. See the Cloud Deployment guide for a Caddy example.

Troubleshooting

API calls fail with connection refused

The web app tries to connect to localhost:8585 instead of your public IP. Verify the environment variable was set:

curl http://YOUR_IP:3000/__ENV.js | grep JAWN
# Should show your public IP, not localhost

Infinite redirect loop

Missing NEXT_PUBLIC_IS_ON_PREM=true environment variable. All URL environment variables must use the same origin (public IP or domain). Don’t mix localhost with public IPs.

”No organization ID found” error

User needs to be added to an organization. See the Organization Setup section above.

​Quick Start (Local)

​Example to test the Jawn service

​Production Setup (Remote Server)

​Environment Variables

​Port Requirements

​User Account Setup

​Create Account

​Email Verification

​Organization Setup

​Supported LLM Providers

​Important Notes

​Data Persistence

​Security

​HTTPS

​Troubleshooting

​API calls fail with connection refused

​Infinite redirect loop

​”Invalid origin” error on sign-in

​”No organization ID found” error