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.

Open it at /dashboard. The root route / redirects there so the first screen is the operational console, not a marketing page.

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/web/src/app/(dashboard)/dashboard/page.tsx renders the primary command center.
  • apps/web/src/app/(dashboard)/dashboard/operations/[serviceId]/page.tsx renders service detail and investigation views.
  • apps/web/src/app/(dashboard)/dashboard/operations/resources/page.tsx renders provider resources and mapping gaps.
  • apps/web/src/app/(dashboard)/dashboard/operations/changes/page.tsx answers what changed recently.
  • apps/api/src/operations contains discovery, inventory upsert, health checks, triage, provider enrichment, 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:cloudflare:check
pnpm ops:verify
pnpm --filter @oath-bringer/api test
pnpm --filter @oath-bringer/web type-check

Discovery will quietly read env-style secrets from:

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

Expected optional variables:

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

Compatibility aliases are also recognized for existing local secret files: GITLAB_MFOX_TOKEN, CLOUDFLARE_TOKEN, and CF_TOKEN. R2/S3 credentials and generic TOKEN_VALUE entries are not Cloudflare management credentials and are ignored by provider discovery.

Diagnostics expose only key names, expected locations, and provider status classes. They must not include token values.

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.

Provider Health States

/api/operations/health separates provider failures into:

  • missing_credentials: required key names are not available to the API runtime.
  • invalid_credentials: the provider rejected the token.
  • permission_denied: the token reached the API but lacks required read permissions.
  • timeout: provider API calls exceeded OPERATIONS_PROVIDER_TIMEOUT_MS.
  • error: provider/network failure that does not fit the specific classes.
  • connected: provider checks completed successfully.

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.