Health and metrics

Three endpoints and a metrics scrape. All of them deliberately need no tenant and no database, so they still answer when the instance is unhealthy.

The endpoints

Endpoint	Answers	Use for
/api/health	Liveness plus build information	“Is the process alive”
/api/health/ready	Readiness, including the database	Load balancer and uptime checks
/api/health/version	Version, channel, commit and build time	“What are you running”

curl -s https://helpdesk.yourschool.org/api/health/version

{
  "version": "0.2.0",
  "channel": "stable",
  "commit": "9f2c1ab44e01",
  "builtAt": "2026-08-01T09:14:22Z"
}

Which one to point things at

Uptime checks and load balancers: /api/health/ready. It answers the question that matters, which is whether the instance can serve a request.

/api/health says the process has not crashed, which is a weaker statement. A process that is up but cannot reach its database passes liveness and fails readiness, and the second is the one you want to know about.

Tenant resolution is skipped

Health and metrics endpoints are exempt from tenant matching. That is what makes them useful during an incident: a misconfigured hostname breaks everything else and these keep answering.

Metrics

Prometheus metrics are exposed for scraping.

plugboard_build_info carries the version as a label. Graph it. It makes fleet-wide “who is on what version” answerable at a glance, and it makes a failed update visible as a version that did not change, which is otherwise an easy thing to miss.

Verifying an update

The update script gates on this. After swapping the image it waits for /api/health/ready to pass and for the instance to report the version it was asked for, within 120 seconds.

The version check exists because a tag that silently resolved to the old image passes every other check and looks like a successful update. See updating.

You can do the same by hand:

curl -s https://helpdesk.yourschool.org/api/health/version | jq -r .version

Error reporting

Errors can be sent to your own collector by setting SENTRY_DSN to a self-hosted Sentry or GlitchTip.

There is no default destination. Nothing is sent anywhere unless you set it.

What to alert on

Covered in keeping an eye on it. The short list:

• /api/health/ready failing twice in a row
• Certificate under 14 days to expiry
• Disk above 85 percent
• Backup failed
• Version unchanged after an update