> ## Documentation Index > Fetch the complete documentation index at: https://docs.foglamp.dev/llms.txt > Use this file to discover all available pages before exploring further. # 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 `/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. |