Configuration

Environment variable reference for a self-hosted deployment.

All services are configured through environment variables, validated at startup (packages/env). Anything with a default is optional; everything else is required. apps/server/.env.example mirrors this reference.

Core

Variable	Required	Default	Description
DATABASE_URL	yes	—	Postgres connection string.
BETTER_AUTH_SECRET	yes	—	Session-signing secret, min 32 chars.
BETTER_AUTH_URL	yes	—	Public URL of apps/server (e.g. http://localhost:3000).
CORS_ORIGIN	yes	—	Dashboard origin allowed to call the API (e.g. http://localhost:3001).
CORS_EXTRA_ORIGINS	no	—	Additional allowed origins, comma/space separated (preview deploys, staging).
PORT	no	3000	Port for apps/server. Usually injected by the host.
NODE_ENV	no	development	development, production, or test.

ClickHouse

Variable	Default	Description
CLICKHOUSE_URL	http://localhost:8123	ClickHouse HTTP endpoint.
CLICKHOUSE_USER	default	Username.
CLICKHOUSE_PASSWORD	“	Password. Empty is fine while ClickHouse is unreachable from outside your network (the base docker-compose.yml keeps 8123 off the host; the dev override publishes it to localhost); the server logs a warning if it’s empty in production.
CLICKHOUSE_DATABASE	foglamp	Database name.

Ingest (apps/ingest)

Variable	Default	Description
INGEST_PORT	4000	Port for the ingest API.
INGEST_FLUSH_INTERVAL_MS	1000	How often the write buffer flushes to ClickHouse.
INGEST_FLUSH_MAX_ROWS	1000	Flush early once this many rows are buffered.
INGEST_RATE_LIMIT_RPS	100	Spans/second budget per API key — a request costs its span count.
INGEST_MAX_BODY_BYTES	10485760	Max request body in bytes; larger requests get 413 before parsing.
REDIS_URL	—	Optional shared Redis for rate limiting across ingest replicas (e.g. redis://redis:6379). Unset → per-instance in-memory limiting, fine for a single replica.
API_KEY_CACHE_TTL_MS	60000	In-memory API-key cache TTL.

Cost & pricing

Variable	Default	Description
OPENROUTER_MODELS_URL	https://openrouter.ai/api/v1/models	Source for model pricing.
FOGLAMP_PRICING_FILE	—	Local pricing JSON for air-gapped hosts.

Alerts (apps/server)

Variable	Default	Description
ALERT_EVAL_INTERVAL_MS	60000	How often the evaluator sweeps enabled rules.
ALERT_RENOTIFY_MS	3600000	Re-notify cooldown while a rule stays firing.

Evals & provider keys (apps/server)

Evals score your traces with bring-your-own-key judge models. The whole feature is gated on FOGLAMP_SECRETS_KEY — without it, provider keys can’t be stored and scoring stays off.

Variable	Default	Description
FOGLAMP_SECRETS_KEY	—	Min 32 chars. AES-256-GCM key encrypting provider API keys at rest. Generate with openssl rand -base64 32. Unset → evals/provider keys disabled.
SCORING_EVAL_INTERVAL_MS	60000	How often the scoring planner sweeps enabled evals and enqueues jobs.
SCORING_SETTLE_MS	60000	Spans newer than this aren’t scored yet, so late spans settle first.
EVAL_JUDGE_CONCURRENCY	5	Max judge LLM calls in flight per eval job.
EVAL_SCORING_BATCH	100	Max targets scored per eval per planner tick.
EVAL_JUDGE_MAX_INPUT_CHARS	200000	Char budget for a judge call’s prompt fields; larger payloads are truncated.
EVAL_EXECUTOR_BATCH	5	Max queued eval jobs the executor claims (and runs) per tick.

Billing — Stripe (optional)

Most self-hosts leave this whole block unset; billing is enabled only when both the secret key and webhook secret are present.

Variable	Default	Description
STRIPE_SECRET_KEY	—	Stripe API secret key.
STRIPE_WEBHOOK_SECRET	—	Webhook signing secret for the Stripe endpoint.
STRIPE_PRICE_ID_PRO_MONTHLY	—	Price ID for the Pro monthly plan.
STRIPE_PRICE_ID_PRO_ANNUAL	—	Price ID for the Pro annual plan.
QUOTA_WARN_INTERVAL_MS	3600000	How often orgs are swept for the 90% span-quota warning email.

Foggy — in-app assistant (optional)

Foggy is enabled only when GOOGLE_GENERATIVE_AI_API_KEY is set.

Variable	Default	Description
GOOGLE_GENERATIVE_AI_API_KEY	—	Gemini API key; unset disables Foggy.
FOGGY_MODEL	gemini-3.1-flash-lite	Model used for chat.
FOGGY_DOCS_URL	https://docs.foglamp.dev	Docs site Foggy’s docs tool fetches llms.txt / llms-full.txt from.
FOGGY_RPM	15	Per-user requests/minute.
FOGGY_DAILY_LIMIT	200	Per-user messages/day.
FOGGY_MAX_STEPS	6	Max tool-use steps per answer.
FOGGY_MAX_OUTPUT_TOKENS	1500	Output token cap per answer.
FOGLAMP_API_KEY	—	Optional: dogfood Foggy’s own LLM calls into a Foglamp project.
FOGLAMP_INGEST_URL	—	Ingest endpoint for the dogfooding key.

Email (optional)

Enables magic-link login and alert notifications. Without these, password login still works.

Variable	Description
RESEND_API_KEY	Resend API key.
RESEND_FROM_EMAIL	From address for outbound email.

Google OAuth (optional)

Enabled only when both are present. Set the OAuth redirect URI in the Google Cloud console to <BETTER_AUTH_URL>/api/auth/callback/google.

Variable	Description
GOOGLE_CLIENT_ID	OAuth client ID.
GOOGLE_CLIENT_SECRET	OAuth client secret.
AUTH_DISABLE_EMAIL_PASSWORD	Set to true to turn off email+password sign-in (e.g. Google + magic link only). Default: enabled.

Platform admin (optional)

Variable	Description
PLATFORM_ADMIN_EMAILS	Comma-separated emails allowed to open the cross-org Platform stats page (instance totals, ingestion volume, ClickHouse storage). Unset: hidden for everyone.

Seed bootstrap

Used once by the seed script. No static defaults — a random password is generated and printed if unset.

Variable	Description
ADMIN_EMAIL	Initial admin email.
ADMIN_PASSWORD	Initial admin password.

Web dashboard (apps/web)

Variable	Description
NEXT_PUBLIC_SERVER_URL	Public URL of apps/server the browser calls.
NEXT_PUBLIC_APP_URL	Public URL of the dashboard itself.
INTERNAL_SERVER_URL	Optional in-cluster server URL for SSR requests.