zolder

Appearance

Alerting ​

zolder has two independent alerting paths, plus a dead-man's switch for the one failure it can't report on itself. All three are optional and configured under [alert] (see the Configuration reference).

ntfy push channel ​

Alerts are delivered as a single HTTP POST to an ntfy topic, sent at high priority so they break through Do-Not-Disturb.

toml
[alert.ntfy]
server = "https://ntfy.sh"       # default; point at a self-hosted ntfy if you run one
topic = "zolder-CHANGE-ME"       # subscribe to this topic on your phone / desktop
# token_file = "/home/demian/.config/zolder/ntfy-token"   # for a protected topic
  • Subscribe to the same topic in the ntfy app (or https://ntfy.sh/<topic>) to receive pushes. Pick an unguessable topic name — on the public server a topic is effectively its own password.
  • For a self-hosted or access-controlled ntfy, set token_file to a file holding a bearer token; zolder sends it as Authorization: Bearer <token>.

Edge-triggered check alerts ​

zolder check compares the current set of failing checks against the previous run's report and alerts only when that set changes:

  • A new failure sends a zolder: checks failing notification listing each failing check and its summary.
  • A recovery (the failing set becomes empty) sends one zolder: recovered notification naming what had been failing.
  • A persistent outage does not re-page. If the same checks keep failing tick after tick, no new notification is sent — you're paged once when it breaks and once when it clears.

This dedup is keyed on the names of the failing checks, so a fresh failure in a different check still pages even while another is already down.

Backup alerts ​

zolder run backup alerts differently: any failed repo raises a zolder: backup failed notification with no deduplication. A backup that didn't run is not a steady state to fall silent on, so every failed run pages.

Heartbeat dead-man's switch ​

Edge-triggered alerts can't cover the case where zolder itself stops running — a crashed binary or an unscheduled timer sends nothing at all. The heartbeat closes that gap:

toml
[alert]
heartbeat_url = "https://hc-ping.com/<uuid>"
  • After every completed zolder check, zolder issues a GET to heartbeat_url on a healthy run, or <heartbeat_url>/fail on an unhealthy one.
  • Point it at an external service such as healthchecks.io. That service alerts you when the pings stop — the failure mode a local tool can't detect about itself.

Use a hosted or independently-hosted checker here: if zolder and the heartbeat service share the same machine, they can fail together and defeat the purpose.