Skip to content

Operations Dashboard

Oath Bringer's operations dashboard is the local-first command center for services, sites, GitLab projects, Cloudflare resources, and self-hosted systems.

Architecture

  • data/operations-inventory.json is the editable source of truth for known services.
  • SQLite stores discovered services, current state, check history, and deployment history.
  • apps/api/src/operations contains discovery, inventory upsert, health checks, triage, and overview aggregation.
  • /api/operations/overview powers the dashboard.
  • /api/operations/discover imports editable inventory plus local repo and SSH host discovery. GitLab and Cloudflare enrichment runs when API tokens are available.
  • /api/operations/enrich records provider status and imports deployment history from GitLab pipelines and Cloudflare Pages.
  • /api/operations/refresh runs health checks and records append-only results.
  • A background scheduler can run discovery, enrichment, and refresh automatically.

Inventory Schema

Each service supports:

  • name, slug, description
  • owner, environment, priority
  • provider, serviceType
  • url, healthUrl, repoUrl
  • gitlabProjectPath, cloudflareZoneId, cloudflareResourceId
  • deployTarget, dependencies, tags, metadata

Use stable slugs. SQLite upserts by slug, so editing a service in JSON keeps its check history attached.

Add A Service

  1. Edit data/operations-inventory.json.
  2. Add the service with at least name, slug, owner, environment, priority, provider, and serviceType.
  3. Add url or healthUrl whenever possible.
  4. Run pnpm ops:discover.
  5. Run pnpm ops:refresh.
  6. Open /dashboard and confirm the service appears.

Local Commands

pnpm ops:discover
pnpm ops:refresh
pnpm ops:verify
pnpm --filter @oath-bringer/api test

Discovery will quietly read env-style secrets from:

  • ~/.secrets/gitlab-ops.env
  • ~/.secrets/gitlab-mfox-agent.env
  • ~/.secrets/Cloudflare

Expected optional variables:

  • GITLAB_TOKEN or GITLAB_PRIVATE_TOKEN
  • GITLAB_BASE_URL
  • CLOUDFLARE_API_TOKEN or CF_API_TOKEN
  • CLOUDFLARE_ACCOUNT_ID or CF_ACCOUNT_ID

Scheduled Refresh

The API process starts a scheduled operations refresh by default.

Configure it with:

  • OPERATIONS_REFRESH_ENABLED=false to disable it.
  • OPERATIONS_REFRESH_INTERVAL_MS=300000 to control interval length.
  • OPERATIONS_REFRESH_INITIAL_DELAY_MS=30000 to control startup delay.

Each scheduled cycle runs inventory discovery, provider enrichment, and health checks with overlap protection.

Production Verification

After deployment:

  1. Run the dashboard verification script against production data.
  2. Confirm /health returns healthy.
  3. Confirm /dashboard loads the operations console.
  4. Trigger a refresh and inspect any degraded or down services.
  5. Spawn a verification agent to independently confirm the production dashboard works.