Build Cronitor

The build, in order

1. 1

   Ping ingestion

   hideshow

   Accept pings on URLs that match the Healthchecks scheme, store them, and never fail a ping because the database is busy.

   1. 1.1Create the project, the database file and the two tables

      checks (id uuid, name, period_seconds, grace_seconds, status, last_ping_at, last_started_at, last_duration_ms) and pings (id, check_id, received_at, kind, exit_code, body). All timestamps as UTC epoch milliseconds. Open SQLite with WAL mode and a busy timeout.

      Files server.mjsdb.mjs.env

      terminalcopy

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

   2. 1.2Route /ping/:uuid and its variants

      GET, POST and HEAD on /ping/:uuid is a success. /ping/:uuid/start records a start, /ping/:uuid/fail a failure, /ping/:uuid/log a log line, and /ping/:uuid/<0-255> treats 0 as success and anything else as failure.

   3. 1.3Store at most 100 kB of a POST body and always answer OK

      Read the body up to 100 kB and stop reading. Answer 200 with the plain text OK. An unknown uuid answers 404 with not found and inserts nothing.

   4. 1.4Add a create-check script for testing

      A tiny CLI that inserts a check row with a name, period and grace and prints its ping URL, so you can test before the dashboard exists.

      terminalcopy

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

   done when · tick each as it passes

   • curl -fsS http://localhost:3000/ping/<uuid> prints OK and one row appears in pings
   • Posting a 2 MB body stores exactly 100 kB and still returns 200
   • A ping to a random uuid returns 404 and creates nothing
   • /ping/<uuid>/7 stores kind fail with exit_code 7

   watch out

   • Store times as UTC epoch milliseconds, never local-time strings. The late maths breaks across a DST change otherwise.
   • Do not validate the body. Jobs post arbitrary output; you store it and show it.

   next phase
2. 2

   Status state machine

   hideshow

   A loop that turns pings into up, late and down, alerts exactly once per transition, and never alerts for a check that has not pinged yet.

   1. 2.1Write the evaluation function

      For each check: up while now is within period of last_ping_at; late once past period; down once past period plus grace. A fail ping sets down at once; any success sets up at once. Status new (never pinged) and paused are skipped.

   2. 2.2Record every transition in an alerts table

      alerts (id, check_id, from_status, to_status, sent_at, delivered, error). Write a row when status changes and only then.

   3. 2.3Compute run duration from /start to success

      When a success follows a start, set last_duration_ms. Show it later so a job that suddenly takes 40 minutes is visible.

   4. 2.4Run the loop on CHECK_INTERVAL_SECONDS in the same process

      setInterval, wrapped in try/catch so one bad row cannot stop the loop. Log one line per transition.

   done when · tick each as it passes

   • A check with period 60 and grace 30 reads up right after a ping, late at 61 seconds and down at 91
   • Exactly one alerts row per transition and none for a repeated loop in the same state
   • A fail ping flips a check to down immediately
   • A new check with no pings never gets an alerts row

   watch out

   • Test the state machine with a fake clock before touching the webhook. Waiting real minutes to see a transition is how this phase eats an evening.

   next phase
3. 3

   Alerting

   hideshow

   One chat message when a job goes down, one when it recovers, retries that never stall the loop.

   1. 3.1Write a sender for your ALERT_FORMAT

      Discord wants {content}, Slack wants {text}, Telegram wants chat_id and text on the bot API. Include the check name, the new status, how late in human units (14 min late) and the last failure body if any.

   2. 3.2Drain undelivered alerts rows after each loop

      Send, mark delivered on 2xx. On failure retry three times with backoff (2 s, 10 s, 60 s), then record the error on the row and move on.

   3. 3.3Send a recovery message on the return to up

      It carries how long the outage lasted, from the down alert's sent_at.

   done when · tick each as it passes

   • Taking a check down produces exactly one message in the channel
   • Leaving it down produces no further messages
   • Recovery produces exactly one message with a duration
   • Pointing ALERT_WEBHOOK_URL at a URL that returns 500 leaves an alerts row with an error and the loop still running

   next phase
4. 4

   Admin dashboard

   hideshow

   Create and manage checks in the browser, and see every job's state at a glance.

   1. 4.1Add basic auth from ADMIN_USER and ADMIN_PASS

      Compare with a constant-time function. Everything under /admin requires it; /ping never does.

   2. 4.2Build the check list

      One row per check: a green, amber or red dot, name, relative last ping (7 min ago), period and grace, and the ping URL with a copy button plus a ready-to-paste crontab example line.

   3. 4.3Add create, edit, pause and delete forms

      Plain HTML forms posting to /admin routes. No JavaScript required for any of them.

   4. 4.4Draw a 24-hour ping histogram per check as inline SVG

      One bar per hour from a GROUP BY on received_at. No chart library.

   done when · tick each as it passes

   • A check can be created, edited, paused and deleted from the browser
   • The page renders correctly with zero checks
   • The histogram bars match a count query for the last 24 hours
   • The ping URL copied from the dashboard works in curl

   next phase
5. 5

   Hardening and deploy

   hideshow

   Live on your VPS behind HTTPS, surviving restarts, with old pings pruned.

   1. 5.1Rate limit /ping per IP, generously

      A legitimate job may ping every minute; allow 120 per minute per IP in memory and answer 429 beyond that.

   2. 5.2Add /healthz and a nightly retention job

      /healthz answers 200 with a quick database read. Retention deletes pings older than RETENTION_DAYS once a day; alerts and checks are never pruned.

   3. 5.3Install on the VPS with systemd and Caddy

      Unit with Restart=on-failure, EnvironmentFile=.env, an unprivileged user. Caddyfile: your domain with reverse_proxy localhost:PORT.

      Files deploy/monitor.serviceCaddyfile

      terminalcopy

      sudo cp deploy/monitor.service /etc/systemd/system/ && sudo systemctl enable --now monitor
      sudo systemctl status monitor

   4. 5.4Add the ping to one real crontab and write the README

      README: the one-liner (*/5 * * * * /path/job.sh && curl -fsS <url>), the wrapper form that reports failures with /start and /fail, and the same-host warning.

      Files README.md

      terminalcopy

      crontab -e
      # 0 3 * * * /home/you/backup.sh && curl -fsS https://ping.yourdomain.com/ping/<uuid>

   done when · tick each as it passes

   • The service comes back with state intact after sudo reboot
   • Retention actually deletes pings older than the window
   • A real cron job on another machine shows up as up on the dashboard
   • The README takes a reader from clone to a monitored job

   watch out

   • Put the monitor on a different machine than the jobs. On the same host it dies with the host, which is precisely when it was supposed to speak.

   next phase