cplieger/knell repository overview

⁠knell

knell is a dead man's switch for your scheduled jobs. It sends you a Discord message when a cron job, backup script or alerting pipeline stops pinging it over HTTP. It only listens and never runs them.

⁠What it does

knell tells you when a scheduled job stops, in four ways:

• Posts once to Discord when a job stays quiet past its deadline, and again when it pings.
• Counts each deadline from knell's start, so a job silent since a restart is still reported.
• Tells you afterwards about an outage that ended before its message could go out.
• Publishes each job's state as Prometheus metrics, so your metrics stack can combine several instances.

Each watched job is a beat. Its deadline is the longest silence allowed between two pings.

⁠Who it is for

knell is built for a home lab that gets its alerts in Discord and wants a small watchdog with no database or web page. It is one static binary set up from environment variables, keeps its state in memory and sends only to Discord or a Discord-compatible relay.

You need a Discord webhook, a Docker host and jobs that can send an HTTP POST. Keep its port on a network you trust.

Two projects suit a different setup:

• Consider Healthchecks⁠ if you want a web dashboard, cron schedules and 25+ integrations.
• Consider Uptime Kuma⁠ if you want status pages and active HTTP, DNS and ping checks.

knell is free software under the GPL-3.0-or-later license.

⁠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"  # one id:deadline pair per job you watch
      DISCORD_WEBHOOK_URL: "https://discord.com/"  # replace with your full Discord webhook URL, or knell refuses to start
      BEAT_TOKEN: "CHANGEME"  # replace with the output of "openssl rand -hex 16", or knell refuses to start
      NODE_NAME: "server-1"  # names this instance in every notice

    ports:
      # /metrics needs no token and lists every beat. Publish this port only to a
      # network you trust, see README "Security".
      - "9190:9190"

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Configuration⁠
• Security⁠
• How knell works⁠
• Monitoring and alerts⁠
• 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/.