Principle:Helicone Helicone Environment Configuration
| Knowledge Sources | |
|---|---|
| Domains | Local Development, Configuration |
| Last Updated | 2026-02-14 00:00 GMT |
Overview
Environment configuration is the practice of externalizing service connection strings, secrets, and feature flags into .env files so that each Helicone service can discover its dependencies at runtime.
Description
Helicone consists of multiple services (web, jawn, worker, Docker infrastructure) that each require environment variables pointing to databases, storage backends, authentication keys, and peer services. The project follows the .env.example pattern: each service directory and the Docker directory contains an .env.example file with documented placeholder values. Developers copy these to .env and adjust values for their local setup.
There are two primary environment files:
- Root
.env.example: Contains 14 variables for the Next.js web frontend and Jawn backend including Supabase URLs, database connection strings, Slack config, and the Jawn service endpoint. docker/.env.example: Contains 151 lines of configuration covering secrets (Better Auth, Postgres password, JWT, S3 keys), ClickHouse settings, worker ports, Jawn configuration, Supabase infrastructure (Kong, PostgREST, Auth, Studio), and logging.
Getting these variables wrong is the most common source of "it doesn't work locally" issues. The principle ensures every developer has a consistent, documented starting point.
Usage
Use this principle immediately after installing prerequisites and cloning the repository, before starting any Docker containers or application services.
Theoretical Basis
The Twelve-Factor App methodology prescribes storing configuration in the environment rather than in code. The .env.example pattern extends this by providing a version-controlled template that documents every required variable. Tools like dotenv (used by Jawn) and dotenv-cli (used by the web frontend) load these files at startup.
Key variable categories in Helicone:
| Category | Example Variables | Purpose |
|---|---|---|
| Database | DATABASE_URL, CLICKHOUSE_HOST |
Connect to PostgreSQL and ClickHouse |
| Authentication | BETTER_AUTH_SECRET, JWT_SECRET, ANON_KEY |
Secure sessions and API access |
| Object Storage | S3_ACCESS_KEY, S3_SECRET_KEY, MINIO_ROOT_USER |
MinIO credentials |
| Service Discovery | NEXT_PUBLIC_HELICONE_JAWN_SERVICE, JAWN_PUBLIC_URL |
Inter-service communication |
| Feature Flags | VERCEL_ENV, NEXT_PUBLIC_BETTER_AUTH |
Toggle behavior per environment |