HUB
Sign inSign up

cplieger/knell

By cplieger

•Updated 3 days ago

Get a Discord message when a cron job, backup script or alerting pipeline stops checking in

Image
Monitoring & observability
0

10K+

cplieger/knell repository overview

⁠knell

knell sends you a Discord message when a cron job, backup script or alerting pipeline stops checking in. Each job pings knell over HTTP. knell never runs the jobs.

⁠What it does

knell tells you when a scheduled job stops running:

  • Posts to Discord when a job misses its deadline, and again when it checks in.
  • Can repeat that post while the job stays silent.
  • Reports a job that never checks in at all, one deadline after knell starts.
  • Reports an outage that ended while Discord was down, once Discord answers again.
  • Publishes each job's state as Prometheus metrics.

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 sends only to a Discord webhook or a relay that accepts Discord's message format. It keeps its state in memory, so a restart starts every deadline over.

You need a Discord webhook, a Docker host and jobs that can send an HTTP POST. Keep its ports 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_TOKENS: |  # one <beat>:<token> line per job, each token from "openssl rand -hex 16"; knell refuses to start until every beat has one
        cron-backup:CHANGEME
        pipeline-watchdog:CHANGEME-TOO
      NODE_NAME: "server-1"  # names this instance in every notice

    ports:
      # Pings. Publish this port only to a network you trust, see README "Security".
      # /healthz and /metrics stay unpublished on 9191: a scraper on this network reaches knell:9191.
      - "9190:9190"

⁠Documentation

⁠License

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

Tag summary

Content type

Image

Digest

sha256:f7a3cce53…

Size

3.6 MB

Last updated

3 days ago

docker pull cplieger/knell