cplieger/knell repository overview

⁠knell

A dead man's switch in a single tiny container: things ping it while they're alive, and when the pings stop, it rings a Discord webhook.

⁠What it does

Monitoring tells you when something visibly breaks. It stays quiet when the thing that was supposed to run simply never ran: the cron job that silently stopped, the alerting pipeline that died along with its own ability to alert. knell watches for that silence.

You configure named beats, each with a deadline. Anything that can send an HTTP request pings its beat (POST /beat/<id>); if a beat stays silent past its deadline, knell posts a missing notice to your Discord webhook, and a recovered notice when the pings return. Per-beat freshness is also exposed as Prometheus metrics, so a metrics stack can aggregate several knell instances into quorum views.

• One binary on a scratch base: no shell, no libc, no dependencies to patch
• Deadline clock starts at boot: a beat that never pings at all still alerts one deadline after start, so a restart never silently disarms the switch (the flip side: each restart re-arms full deadlines; see the restart-churn rule under Alerting)
• One missing notice per live outage (delivery is retried every sweep until it succeeds), one recovered notice when the beat returns
• Outages that were already over before anything could be sent are reported once, in the past tense, with the reason the notice is late, instead of arriving as apparent new failures
• Unknown beat ids are rejected with 404 and never create metric series

⁠Pull

docker pull cplieger/knell:latest

Also published to ghcr.io/cplieger/knell with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for knell. See the README for all configuration options and hardening.
services:
  knell:
    image: ghcr.io/cplieger/knell:latest
    container_name: knell
    restart: unless-stopped

    environment:
      BEATS: "cron-backup:26h,pipeline-watchdog:20m"  # id:deadline list, see README
      DISCORD_WEBHOOK_URL: "https://discord.com/"  # invalid placeholder; replace with the full Discord webhook URL
      BEAT_TOKEN: "CHANGEME"  # invalid placeholder; replace with: openssl rand -hex 16
      NODE_NAME: "server-1"  # names this observer in notifications

    ports:
      # /metrics is unauthenticated and enumerates beats; set ALLOWED_HOSTS
      # and restrict exposure -- see README "Configuration reference".
      - "9190:9190"

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Releases and changelog⁠

⁠License

GPL-3.0-or-later. See LICENSE⁠. The image carries the license text of every bundled component under /usr/share/licenses/.