Skip to main content
Foglamp is built to run anywhere Docker runs. The same code powers the hosted service and your self-hosted deployment — there is no separate “community edition” with features stripped out.

​
Architecture

                    ┌──────────────┐
   your apps ──────▶│ apps/ingest  │──┐
   (SDK)            │  :4000       │  │  writes
                    └──────────────┘  ▼
                                  ┌────────────┐
                                  │ ClickHouse │  spans + rollups
                                  └────────────┘
                                  ┌────────────┐
                                  │ Postgres   │  orgs, projects, keys, alerts
                                  └────────────┘
                    ┌──────────────┐  ▲
   dashboard ──────▶│ apps/server  │──┘  reads + auth + alert cron
   (browser)        │  :3000       │
                    └──────┬───────┘
                    ┌──────▼───────┐
                    │ apps/web     │  Next.js dashboard
                    │  :3001       │
                    └──────────────┘
ServicePortRole
apps/ingest4000API-key-authed span intake; prices and writes spans. Scales independently.
apps/server3000tRPC dashboard API, auth, and the alert evaluator cron.
apps/web3001Next.js dashboard UI.
ClickHouse8123Span store and materialized rollups.
Postgres5432Orgs, projects, API keys, alerts.
There is no external queue — the ingest write buffer is in-memory and flushes to ClickHouse on an interval and on graceful shutdown, and eval scoring jobs queue in Postgres. Redis is optional: when REDIS_URL is set, ingest rate limiting is shared across replicas; unset, each instance limits in memory (fine for a single replica). The default compose includes a Redis service.
Which ports reach the host depends on the compose files in play. The base docker-compose.yml keeps ClickHouse’s 8123 internal-only — reachable from the other services but not published on the host. A plain docker compose up also loads docker-compose.override.yml, which publishes 8123 (plus Postgres 5432 and Redis 6379) to localhost for local development. For a production self-host, run without the override — docker compose -f docker-compose.yml up --build — and set CLICKHOUSE_PASSWORD before the network is reachable; an open passwordless ClickHouse leaks every span.

​
Quickstart

git clone https://github.com/foglamp-labs/foglamp.git
cd foglamp
docker compose up --build
On boot the stack runs Drizzle migrations, applies the ClickHouse DDL, sets span retention, and runs the idempotent seed script (the one-shot migrate service). The seed prints an admin login and an API key once — copy them. If you missed them, search the migrate service logs for Save these now (docker compose logs migrate).
There are no static default credentials. If ADMIN_EMAIL / ADMIN_PASSWORD are unset, the seed generates a random password and prints it a single time.
Then open the dashboard at http://localhost:3001 and log in with the seeded email + password. Email (magic-link) and Google OAuth are optional — login works out of the box without them.

​
Pointing the SDK at your deployment

Set the ingest URL in your instrumented app: 
FOGLAMP_API_KEY=fl_seeded_key_here
FOGLAMP_INGEST_URL=http://your-host:4000/ingest

​
Operations

  • Retention — span retention is plan-driven: each span is stamped with a retention_days value at ingest (from the org’s plan) and a per-row TTL expires it automatically. Hosts running with billing off keep spans effectively forever.
  • Pricing — model prices come from the OpenRouter models API, cached and refreshed every 24h. For air-gapped hosts, supply a local JSON file with FOGLAMP_PRICING_FILE.
  • Email — set RESEND_API_KEY to enable magic-link login and alert notifications. Without it, the platform still works via password login.
See Configuration for the full environment variable reference.