Skip to content
plugboard.appRequest a demo

Install it yourself

Keeping an eye on it

These need no tenant and no credential. Only /api/health/live and /api/health/version avoid the database entirely; the others query it and report what they find.

EndpointAnswers
/api/healthProcess up, plus database state, version and channel. Answers 200 even when the database is down, reporting degraded
/api/health/liveLiveness only. No dependency checks
/api/health/readyReadiness. Returns 503 when the database cannot be reached
/api/health/versionVersion and release channel. No database check
Terminal
curl -s https://helpdesk.yourschool.org/api/health/version
JSON
{ "version": "0.1.0", "channel": "stable" }

They also need no credential, which is why they say this much and no more. The version names a release; the git commit and the build timestamp name one exact image, and since the release notes say which security fixes are in which release, publishing both to anybody who asks would answer whether your instance still carries a given bug.

To read the exact build, set BUILD_INFO_TOKEN to a long random string, restart, and present it:

Terminal
curl -s -H "Authorization: Bearer $BUILD_INFO_TOKEN" \
https://helpdesk.yourschool.org/api/health/version
JSON
{ "version": "0.1.0", "channel": "stable", "commit": "9f2c1ab44e01", "builtAt": "2026-08-01T09:14:22Z" }

With no token configured, which is the default, nobody gets the commit. A missing or wrong token is answered with the short form rather than an error, so setting this can never stop a health check working.

Point your uptime checker at /api/health/ready. Point your load balancer at the same. /api/health and /api/health/live answer 200 whenever the process is alive, so they do not tell a load balancer that the database is gone.

Prometheus metrics are exposed for scraping, including plugboard_build_info, which carries the version as a label. Graph it: it shows which version each instance is on, and a failed update shows up as a version that did not change.

/api/metrics is open unless you set METRICS_TOKEN, so it carries the same restraint as the health endpoints: plugboard_build_info is labelled with the version and the channel, and gains a commit label only once a token is required to scrape it.

plugboard_csp_reports_total counts the reports browsers send about the desk’s script policy, which is report-only until you set CSP_ENFORCE. The report endpoint only counts: it never reads what a report contains. A count that keeps rising means something on a page would be blocked under the enforced policy; one that stays still through normal use means you can enforce it. With EMBED_ORIGINS set, no reports are sent at all, so the count stays at zero whatever the pages do.

Use the row for the deployment actually installed. Native release packaging currently targets Linux x64; Windows/macOS paths are reference-launcher instructions and do not imply available packages.

InstallWhere
systemdjournalctl -u plugboard -f
Validated reference bundle on Windows or macOSlogs/ inside the install directory

Native startup restricts retained logs to the installation owner (plus SYSTEM and administrators on Windows). Setup, tracking and feedback link paths are redacted in application logs and native diagnostics. Do not use old logs to recover an administrator account: use the private recovery flow below.

Errors can also be sent to your own collector. Set SENTRY_DSN to a self-hosted Sentry or GlitchTip. There is no default destination, and nothing is sent anywhere unless you set it.

In rough order of how much it will matter at 8:40 on a Monday.

AlertConditionWhy
Instance down/api/health/ready fails twice in a rowEverything else is downstream of this
Certificate expiringUnder 14 daysThe most common self-inflicted outage
Disk above 85 percentOn the volume holding the database and backupsA full disk stops PostgreSQL and stops backups, in that order
Backup failedThe backup.failed eventYou find out now, not during a restore
Version unchanged after an updateplugboard_build_info still shows the old versionA tag that resolved to the old image
Database connections near the limitDepends on your max_connectionsUsually a sign something is holding transactions open

Plugboard has its own service monitor for the things around it: the intranet, the print server, the Wi-Fi controller, a connector agent’s heartbeat. That is for the services your users depend on.

Do not use it to monitor Plugboard itself. A monitor that lives inside the thing it is watching cannot tell you the thing is down.

  • External uptime check on /api/health/ready, from outside the school network if the desk is reachable from outside.
  • Plugboard’s own monitors for everything else you run, with the ones your community cares about marked public so they land on the status page.
  • Email alerts going to a monitored mailbox, not a personal one. The monitor.down and backup.failed messages are the two that matter.
TaskFrequency
Confirm a backup completed and verify oneWeekly, automated
Restore a backup somewhere and sign inAnnually, by hand
Review the audit log for accounts that should be goneTermly
Check for a new release and read its changelogMonthly
Review connectors still in demo modeAfter any onboarding
Confirm certificate renewal happenedWhenever it renews

Plugboard is not demanding, and the numbers that grow are predictable.

  • The audit log is the largest table on any mature install. Retention is configurable; see audit and retention.
  • Submissions and tickets grow linearly with the desk’s workload and are small.
  • Realtime connections cost one open HTTP connection per signed-in console tab. A desk with twelve technicians is not a load problem.

If the database is slow, check that endpoint protection is not scanning every write to the data directory. That is the usual answer on Windows.

Source and container administrator recovery

Section titled “Source and container administrator recovery”

For a built source installation, run node scripts/plugboard.mjs setup-link <admin-email> under the account that owns its protected .env. Add --embedded-db for an installation using the built-in database. Inside an API container, use --from-environment to select its injected configuration.

The named address must identify one active school administrator. The command writes owner-private .setup-link.html, prints only that file’s path, and audits the operation. Open the file to claim the account. The link works once for four hours and replaces any previous setup link; creating it does not change the password. Remove the file after use. Never send it with diagnostics.