PeerDB Monitoring

Open as Markdown

CHM includes an optional, view-only PeerDB section (Mirrors and Peers) that surfaces replication status, throughput, lag, and per-mirror detail from a PeerDB deployment. CHM never mutates PeerDB — it proxies a read-only allowlist of the PeerDB REST API.

Open it at /peerdb once configured. The section is hidden until PEERDB_API_URL is set.

Enable

Set PEERDB_API_URL (and PEERDB_PASSWORD if your PeerDB API requires auth), then restart the app.

## PeerDB UI behind NextAuth — include the /api suffix
PEERDB_API_URL=https://peerdb.example.com/api
PEERDB_PASSWORD=your-peerdb-ui-password

## OR a raw flow-api with no auth — use the bare origin
PEERDB_API_URL=http://localhost:8113

Variable	Default	Description
`PEERDB_API_URL`	—	Base URL of the PeerDB REST API. For the PeerDB UI (NextAuth) include the `/api` suffix; for a raw flow-api use the bare origin (e.g. `http://host:8113`).
`PEERDB_PASSWORD`	—	Sent as HTTP Basic with an empty username (`base64(":" + password)`). Leave empty if the API has no auth. Server-side only — never sent to the browser.
`PEERDB_CACHE_TTL_MS`	`10000`	TTL for the server-side response cache (set `0` to disable).
`PEERDB_CACHE_MAX_ENTRIES`	`500`	Max cached responses before oldest entries are evicted.
`PEERDB_FETCH_TIMEOUT_MS`	`10000`	Upstream request timeout.

See the full list in Environment Variables.

Connection status

The header shows a status pill that distinguishes:

Connected — API reachable and authenticated.
Auth failed — credentials rejected (check PEERDB_PASSWORD). For the PeerDB UI this is the UI login password.
Unreachable — wrong PEERDB_API_URL or a network/DNS issue.
Not configured — PEERDB_API_URL is unset.

Security

CHM proxies only a read-only allowlist of PeerDB endpoints (app/api/v1/peerdb/[...slug]). Mutating endpoints (create/drop/pause, alert config, maintenance) are rejected with 403. The PeerDB credential is attached server-side and never reaches the browser bundle, and secret-shaped peer config fields are masked in the UI.

The section also respects Feature Permissions — gate it with CHM_FEATURE_PEERDB_ACCESS=authenticated or disable it with CHM_FEATURE_PEERDB_ENABLED=false. The proxy enforces the same gate, so it cannot be reached directly when the feature is disabled or restricted.

Local development (mock)

To preview the full UI without a real PeerDB instance, run the bundled mock server:

bun run peerdb:mock                                  # serves :8113
PEERDB_API_URL=http://localhost:8113 bun run dev     # → /peerdb

Troubleshooting

Symptom	Likely cause
Pill shows Auth failed	Wrong `PEERDB_PASSWORD`. For the PeerDB UI, use the UI login password; for a raw flow-api, match its configured password (or leave empty).
Pill shows Unreachable	`PEERDB_API_URL` host/port wrong, or the API is not reachable from the CHM server.
Mirrors load but charts are empty	The mirror has no recent CDC graph/batch data yet, or the PeerDB version doesn’t expose those endpoints.
Large fleets show partial KPI totals	Per-row metrics load lazily above 24 mirrors; the Throughput/Rows-synced cards label how many mirrors are loaded. Expand a row to load its metrics.