feat: Add file-based dashboard provisioner

[ZeynelKoca]

Summary

Add a provision-dashboards task that reads .json files from a directory and upserts dashboards into MongoDB, following the existing task system pattern (same as check-alerts).

Provisioned dashboards are flagged with provisioned: true so they never overwrite user-created dashboards with the same name. Files are validated against DashboardWithoutIdSchema. Removing a file does not delete the dashboard (safe by default, same as Grafana). The task is deployment-agnostic: it reads from a directory, regardless of how files get there.

When DASHBOARD_PROVISIONER_DIR is set, entry.prod.sh automatically starts the task as an additional process alongside the API, App, and check-alerts.

Note: Users can currently edit provisioned dashboards through the UI, but changes will be overwritten on the next sync cycle. Grafana handles this by blocking saves on provisioned dashboards. Adding a similar guard would be a good follow-up to improve UX.

Variable	Required	Default	Description
DASHBOARD_PROVISIONER_DIR	Yes		Directory to read .json files from
DASHBOARD_PROVISIONER_TEAM_ID	No*		Scope to a specific team ID
DASHBOARD_PROVISIONER_ALL_TEAMS	No*	false	Set to true to provision to all teams

*One of DASHBOARD_PROVISIONER_TEAM_ID or DASHBOARD_PROVISIONER_ALL_TEAMS=true is required.

How to test locally or on Vercel

1. Create a directory with a dashboard JSON file:

   mkdir /tmp/dashboards
   echo '{"name":"Test Dashboard","tiles":[],"tags":[]}' > /tmp/dashboards/test.json

2. Run the task:
   DASHBOARD_PROVISIONER_DIR=/tmp/dashboards DASHBOARD_PROVISIONER_ALL_TEAMS=true
   ./packages/api/bin/hyperdx task provision-dashboards
3. Verify the dashboard appears in the UI
4. Modify the JSON file, run again, verify it updates
5. Delete the JSON file, run again, verify the dashboard persists

References

• Related PRs: HyperDX Dashboard Provisioner ClickHouse/ClickStack-helm-charts#190

[changeset-bot]

🦋 Changeset detected

Latest commit: 0828fbc

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@hyperdx/api	Minor
@hyperdx/app	Minor
@hyperdx/otel-collector	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

@ZeynelKoca is attempting to deploy a commit to the HyperDX Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

PR Review

✅ No critical issues found.

A few minor observations (non-blocking):

• ⚠️ entry.prod.sh only checks DASHBOARD_PROVISIONER_DIR; if the user sets it without TEAM_ID/ALL_TEAMS, the task will silently fail-and-retry every minute (validation throw is caught in tasks/index.ts:main). Consider a friendlier startup check in entry.prod.sh (or surface a one-time WARN log) → not a correctness bug, just UX.
• ⚠️ syncDashboards does a non-atomic Dashboard.exists warning lookup before the upsert. If a user creates a dashboard with the same name between those two ops, only the warning is missed — the partial unique index { name, team } (provisioned-only) still guarantees data integrity. Acceptable.
• ℹ️ asyncDispose closes the mongoose connection on every cron tick (re-opened via connectDB() in execute). This mirrors the checkAlerts provider pattern, so it's consistent — flagging only because it's worth being aware of for long-running deployments.
• ℹ️ Known UX limitation already called out in the PR description: provisioned dashboards remain editable in the UI and get overwritten next sync. Follow-up to block edits would be valuable but is out of scope.

Nice test coverage — both unit (readDashboardFiles) and integration (syncDashboards, full task) paths are exercised, including the user-vs-provisioned coexistence case.

[github-actions]

🔴 Tier 4 — Critical

Touches auth, data models, config, tasks, OTel pipeline, ClickHouse, or CI/CD.

Why this tier:

• Critical-path files (4):
  • docker/hyperdx/entry.prod.sh
  • packages/api/src/tasks/index.ts
  • packages/api/src/tasks/provisionDashboards/index.ts
  • packages/api/src/tasks/types.ts

Review process: Deep review from a domain expert. Synchronous walkthrough may be required.
SLA: Schedule synchronous review within 2 business days.

Stats

• Production files changed: 5
• Production lines changed: 200 (+ 351 in test files, excluded from tier calculation)
• Branch: feature/dashboard-provisioner
• Author: ZeynelKoca

To override this classification, remove the review/tier-4 label and apply a different review/tier-* label. Manual overrides are preserved on subsequent pushes.

[ZeynelKoca]

@dhable Gentle bump to avoid the rebase-loop hell