Build Healthchecks.io

The build, in order

1. 1

   Ping ingestion

   hideshow

   Accept pings on the Healthchecks scheme so existing crontab snippets port unchanged.

   1. 1.1Create the project and the tables

      checks (id uuid, name, period_seconds, grace_seconds, status, last_ping_at, last_started_at, last_duration_ms), pings (id, check_id, received_at, kind, exit_code, body), alerts (id, check_id, from_status, to_status, sent_at, delivered, error). UTC epoch milliseconds throughout.

      terminalcopy

      mkdir heartbeats && cd heartbeats && git init && npm init -y && npm pkg set type=module
      mkdir -p data && cp .env.example .env

   2. 1.2Route GET, POST and HEAD on /ping/:uuid plus /start, /fail, /log and /:exit_code

      0 is success, 1-255 failure. Store at most 100 kB of body. Always answer 200 OK; unknown uuids 404.

   3. 1.3Add a small CLI to create a check for testing
      terminalcopy

      node scripts/add-check.mjs "nightly backup" 86400 1800

   done when · tick each as it passes

   • curl -fsS to a real uuid prints OK and inserts one row
   • A 2 MB body stores exactly 100 kB and returns 200
   • A random uuid returns 404 without creating anything

   watch out

   • Never local-time strings for timestamps; the late maths breaks across DST.

   next phase
2. 2

   State machine

   hideshow

   up, late, down, computed every 30 seconds, one alerts row per transition.

   1. 2.1Write the evaluation: up within period, late past period, down past period plus grace; fail pings flip down at once; new and paused never alert
   2. 2.2Record transitions in alerts and durations from /start to success

   done when · tick each as it passes

   • Period 60 with grace 30 reads up, late at 61 s, down at 91 s
   • Exactly one alerts row per transition
   • A new check never alerts

   next phase
3. 3

   Alerting

   hideshow

   One message per state change with retries that never stall the loop.

   1. 3.1Write the sender for ALERT_FORMAT and drain undelivered alerts after each loop
   2. 3.2Retry three times with backoff, then record the error on the row

   done when · tick each as it passes

   • Taking a check down produces exactly one message
   • Recovery produces exactly one
   • A webhook that 500s leaves an error on the row and the loop running

   next phase
4. 4

   Dashboard

   hideshow

   Manage checks in the browser and see every job at a glance.

   1. 4.1Basic auth on /admin with CRUD and the ping URL plus a crontab line per check
   2. 4.2A status dot, relative last ping and a 24-hour histogram as inline SVG

   done when · tick each as it passes

   • Create, edit, pause and delete work in the browser
   • Renders with zero checks
   • Histogram matches a count query

   next phase
5. 5

   Hardening and deploy

   hideshow

   Rate limits, retention, HTTPS, a real crontab.

   1. 5.1Rate limit /ping generously per IP; add /healthz and nightly retention
   2. 5.2systemd unit, Caddy, one real crontab line, the README

      README: the one-liner with && curl -fsS, the /start and /fail wrapper, the same-host warning, and a line that Healthchecks.io is open source if you outgrow this.

      Files README.mddeploy/heartbeats.serviceCaddyfile

      terminalcopy

      # */5 * * * * /path/job.sh && curl -fsS https://hc.yourdomain.com/ping/<uuid>

   done when · tick each as it passes

   • State survives a reboot
   • A real cron job on another machine shows up
   • The README reaches a monitored job

   next phase