Configuration

Environment variable reference for a self-hosted deployment.

All services are configured through environment variables, validated at startup. 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	none	Postgres connection string.
BETTER_AUTH_SECRET	yes	none	Session-signing secret, at least 32 chars.
BETTER_AUTH_URL	yes	none	Public URL of apps/server (e.g. http://localhost:3000).
CORS_ORIGIN	yes	none	Dashboard origin allowed to call the API (e.g. http://localhost:3001).
CORS_EXTRA_ORIGINS	no	none	Extra allowed origins, comma or space separated (preview deploys, staging).
PORT	no	3000	Port for apps/server. Usually set 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	empty	Password. Empty is fine while ClickHouse is unreachable from outside your network (the base docker-compose.yml keeps 8123 off the host). The server warns 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 per second per API key. A request costs its span count.
INGEST_MAX_BODY_BYTES	10485760	Max request body in bytes. Larger requests get a 413.
REDIS_URL	none	Optional shared Redis for rate limiting across ingest replicas (e.g. redis://redis:6379). Unset means per-instance limiting, fine for one replica.
API_KEY_CACHE_TTL_MS	60000	In-memory API-key cache lifetime.

Cost and pricing

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

Alerts (apps/server)

Variable	Default	Description
ALERT_EVAL_INTERVAL_MS	60000	How often enabled rules are checked.
ALERT_RENOTIFY_MS	3600000	Cooldown between repeat emails while a rule keeps firing.

Evals and provider keys (apps/server)

Evals score your traces with judge models using your own provider keys. The whole feature depends on FOGLAMP_SECRETS_KEY: without it, provider keys can’t be stored and scoring stays off.

Variable	Default	Description
FOGLAMP_SECRETS_KEY	none	At least 32 chars. Encrypts provider API keys at rest. Generate with openssl rand -base64 32. Unset disables evals and provider keys.
SCORING_EVAL_INTERVAL_MS	60000	How often enabled evals are swept and jobs queued.
SCORING_SETTLE_MS	60000	Spans newer than this aren’t scored yet, so late spans can 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 sweep.
EVAL_JUDGE_MAX_INPUT_CHARS	200000	Character budget for a judge call’s prompt fields. Larger payloads are cut off.
EVAL_EXECUTOR_BATCH	5	Max queued eval jobs claimed and run per tick.

Billing with Stripe (optional)

Most self-hosts leave this block unset. Billing turns on only when both the secret key and webhook secret are present.

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

Foggy, the in-app assistant (optional)

Foggy turns on only when GOOGLE_GENERATIVE_AI_API_KEY is set.

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

Email (optional)

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

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

Google sign-in (optional)

Turns on 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 and password sign-in (e.g. Google and magic link only). Default: enabled.

Platform admin (optional)

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

Seed bootstrap

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

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 server-side requests.