> ## 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.

# Self-hosting

> Run the full Foglamp stack on your own infrastructure.

Foglamp runs anywhere Docker runs. The same code powers the hosted service and
your self-hosted deployment. There is no separate "community edition" with
features removed.

## 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       │
                    └──────────────┘
```

| Service       | Port | Role                                                                                      |
| ------------- | ---- | ----------------------------------------------------------------------------------------- |
| `apps/ingest` | 4000 | Receives spans from the SDK, checks API keys, prices and stores spans. Scales on its own. |
| `apps/server` | 3000 | Dashboard API, auth, and the alert checker.                                               |
| `apps/web`    | 3001 | Next.js dashboard UI.                                                                     |
| ClickHouse    | 8123 | Span store and rollups.                                                                   |
| Postgres      | 5432 | Organizations, 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 shutdown, and eval scoring jobs queue in
Postgres. Redis is optional: with `REDIS_URL` set, rate limiting is shared
across ingest replicas; without it, each instance limits on its own, which is
fine for a single replica. The default compose file includes Redis.

<Note>
  Which ports are reachable from the host depends on which compose files you
  use. The base `docker-compose.yml` keeps ClickHouse's 8123 internal only. A
  plain `docker compose up` also loads `docker-compose.override.yml`, which
  publishes 8123, Postgres 5432, and Redis 6379 on `localhost` for local
  development. For production, run without the override
  (`docker compose -f docker-compose.yml up --build`) and set
  `CLICKHOUSE_PASSWORD` before the network is reachable. An open ClickHouse
  with no password exposes every span.
</Note>

## Quickstart

```bash theme={null}
git clone https://github.com/foglamp-labs/foglamp.git
cd foglamp
docker compose up --build
```

On boot the stack runs migrations, sets up ClickHouse, and runs the seed
script. 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`).

<Note>
  There are no default credentials. If `ADMIN_EMAIL` and `ADMIN_PASSWORD` are
  unset, the seed generates a random password and prints it a single time.
</Note>

Then open the dashboard at `http://localhost:3001` and log in with the seeded
email and password. Magic-link email and Google sign-in are optional; login
works out of the box without them.

## Pointing the SDK at your deployment

Set the ingest URL in your instrumented app:

```bash theme={null}
FOGLAMP_API_KEY=fl_seeded_key_here
FOGLAMP_INGEST_URL=http://your-host:4000/ingest
```

## Operations

* **Retention**: how long spans are kept depends on the plan. Each span is
  stamped with a `retention_days` value when it arrives, and expires on its
  own after that. Hosts with billing off keep spans effectively forever.
* **Pricing**: model prices come from the OpenRouter models API, cached and
  refreshed every 24 hours. 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 emails.
  Without it, everything else still works via password login.

See [Configuration](/self-hosting/configuration) for the full environment
variable reference.