Skip to content
sm26449Public

About

Self-hosted alerting and notification service: MQTT, webhooks, HTTP polling and Alertmanager feed rules that fire alerts to Telegram, ntfy, Gotify, Pushover, SMS, email, Web Push and webhooks — with incidents, escalation, quiet hours and an admin UI.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

122 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Klopot — alerts, declared once, delivered anywhere

Klopot

Declare an alert once. Deliver it anywhere.
A self-hosted, API-driven notification microservice — you declare inputs, rules, templates and channels; it evaluates and delivers, with throttling, retries and a full audit trail.

CI Release Container image License Python 3.12 klopot.dev OpenSSF Scorecard

Apache-2.0 · Python 3.12 · FastAPI · MySQL 8 · Română

Klopot admin UI — dashboard

Naming. The product is Klopot; the daemon, its image entry point and its ALERTD_* settings are still called alertd through 1.x. Klopot was born as the alerting service of a home-energy monitoring stack, but nothing in it is domain-specific.

Release status. 1.2.0 (2026-11-16) is the current release — ready to face the internet: a private-by-default proxy, budgets on every way in, and per-key / per-input address and rate limits; several defaults are stricter, so read its upgrade notes. 1.1.1 removed the default passwords. 1.1.0, on top of the 1.0.x durable escalation, rule incidents, Telegram actions, MQTT output and operational monitoring it adds Alertmanager/Grafana ingestion, native ntfy / Gotify / Pushover, SMS providers, packs, a setup guide, the activity log, Web Push to an installable admin UI and generated client SDKs. Read the upgrade notes before upgrading an existing install; project status summarises the release.


Fire an alert from anything that can make an HTTP request — a script, a cron job, Node-RED, another service. The caller needs only an API key and an alert type; Klopot owns routing, channels and secrets:

curl -X POST https://your-host/v1/fire \
  -H "X-API-Key: $KLOPOT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type": "backup_failed", "context": {"job": "nightly-db", "error": "timeout"}}'
{ "id": "ntf_1794139677372_7fc1…", "dispatched": true,
  "channels": ["ui_default", "telegram_oncall"], "status": "sent",
  "title": "Backup failed: nightly-db", "severity": "warning" }

Works with

Delivery channels — add one by configuration, no code:

UI (live WebSocket) · Telegram · SMS (via a gateway) · Email · Web Push (the admin UI installs as an app, iPhone included) · MQTT · ntfy · Gotify · Pushover (incl. emergency until acknowledged) · Slack / Discord / Home Assistant (generic webhook)

Telegram supports opt-in acknowledgement and snooze buttons through a dedicated bot. See the setup and action semantics (Romanian).

MQTT output publishes JSON with stable replay identities. Operational monitoring includes an admin page, Prometheus metrics, a Grafana dashboard and example alert rules.

Native ntfy, Gotify and Pushover, the SMS providers (http, twilio, teltonika) and Web Push devices (details) arrived in 1.1.0.

Client libraries (install from sdk/): Python klopot-client and TypeScript @klopot/client — await klopot.fire("disk_full", { host: "nas" }). See sdk/README.md.

Inputs — where values come from: MQTT · HTTP poll · inbound webhook · inbound SMS · cron schedules · Alertmanager / Grafana.

Try it in two minutes

A self-contained demo (Klopot + MySQL + Mosquitto + a sine-wave sensor + a webhook sink) that fires a real alert end to end:

git clone https://github.com/sm26449/klopot.git
cd klopot
export ALERTD_BOOTSTRAP_ADMIN_KEY="alertd_$(python3 -c 'import secrets; print(secrets.token_urlsafe(32))')"
docker compose -f compose.demo.yml up -d --build
./demo/smoke.sh          # asserts a notification reaches the sink within 2 min
docker compose -f compose.demo.yml down -v

Run it for real

Production uses MySQL 8 only. SQLite is an in-memory test harness, with a separate real-MySQL test gate; it is not a runtime fallback. See testing.

Requirements: Docker with Compose v2 (docker compose), MySQL 8 (the bundled container or your own server), and an x86-64 host — the published image is linux/amd64 only (other platforms build from source). Klopot typically uses ~150 MB of RAM; see resource limits.

cp .env.example .env        # DB passwords, MQTT broker, admin password, channel secrets
docker compose up -d        # Klopot + MySQL + nightly backups, port 127.0.0.1:5090
open http://localhost:5090/admin/     # admin UI
open http://localhost:5090/docs       # OpenAPI / Swagger (open on plain-HTTP localhost)

Compose variants that ship with the repo:

Variant Command
Production, no proxy docker compose up -d
Production behind traefik (TLS), private to your LAN/VPN docker compose -f docker-compose.yml -f compose.traefik.yml up -d
… plus POST /v1/fire open to the internet, with limits docker compose -f docker-compose.yml -f compose.traefik.yml -f compose.public.yml up -d
Development (builds locally, bundled MQTT broker) docker compose -f docker-compose.yml -f compose.dev.yml up --build

Migrations run on startup. Deploy covers the traefik setup (docker or file provider), backups and upgrades. Then follow Getting Started, or install a ready-made pack from Admin UI → Packs (service heartbeat, sensor threshold, Alertmanager — see Packs).

Screenshots

Every alert with its delivery per channel — sent, deferred by the provider, retried
Every alert with its delivery per channel — sent, deferred by the provider, retried
Incidents: detection to recovery, acknowledgement separate from resolution
Incidents: detection to recovery, acknowledgement separate from resolution
Rules grouped by category, with their last firing
Rules grouped by category, with their last firing
Template editor with a live preview from current values
Template editor with a live preview from current values
Activity: every attempt to a provider, with its HTTP answer
Activity: every attempt to a provider, with its HTTP answer
Web Push to the installed app — per device, per severity
Web Push to the installed app — per device, per severity

Synthetic demo data; regenerate with scripts/screenshots.sh. The admin UI also works on a phone and installs as an app.

Features

  • API-first. Every input, variable, rule, template, channel, route and schedule is a DB row, editable over REST. Live OpenAPI at /docs.
  • Rules. A whitelisted expression language (no raw eval), N-of-N persistence, per-rule eval interval, Alertmanager-style inhibition.
  • Incidents (opt-in). Track rule problems through acknowledgement and recovery, with hysteresis and optional recovery notices. Details.
  • Gating. Enable flags, snooze (type / rule / channel), quiet hours, min-repeat throttling, duplicate coalescing.
  • Durable delivery (at-least-once). A fire is persisted with a per-channel delivery row before any external send; a background worker retries failures with backoff and reconciles after a restart.
  • Observability. An Operations page for queues, workers and connections; Prometheus /v1/metrics, portable Grafana dashboard and alert rules; structured logs, request trace ids and configuration audit.
  • Activity log. Every request received, every attempt to a provider with its HTTP exchange, and state changes of inputs, rules and channels, with editable keep / ignore rules. Details.
  • Packs and import / export. Install ready-made configuration with parameters, export any selection as a pack, and import item by item with a preview. Details.
  • Admin UI at /admin — a dependency-light, build-less SPA to manage it all, watch the live log, and test channels: a setup guide for a new installation, global search (Ctrl+K / ⌘K), English and Romanian, light / dark and OS-native themes, phone layout, installable as an app for Web Push (keyboard-accessible, AA contrast).

How it works, in one paragraph

Klopot subscribes to the declared inputs and keeps a live state cache of variable values. Every few seconds it evaluates each enabled rule against that cache; a rule that matches for its required consecutive ticks builds an envelope for the dispatcher. The dispatcher applies gating, then persists a notifications_log row and a deliveries row per routed channel in one transaction before sending. It makes a synchronous first attempt; any channel that fails retryably stays pending and a background delivery worker retries it with backoff. Channel adapters enforce their own rate limits and circuit breakers, and every config change is audited.

Documentation

Doc What it covers
Getting Started · RO Core concepts + an end-to-end walkthrough
API Reference · RO Every REST + WebSocket endpoint, auth, errors
Deploy & Operations Install, env vars, backups, upgrades, rollback
Project status Released baseline, later work, verified deployment and next steps
Operational monitoring Queue visibility, metrics, Grafana and Prometheus setup
MQTT output · Telegram actions Setup, replay identities, acknowledgement and snooze
Architecture Components, data flow, the transactional outbox
Expression language Rule condition syntax + built-in functions
Packs Install, write and export packs (config with parameters)
Activity log · Web Push What is recorded and kept; notifications on a device without an app
All docs → The full index

License & contributing

Licensed under the Apache License 2.0 — see LICENSE and NOTICE. Bundled frontend runtime (vendored, build-less): Preact (MIT) · htm (Apache-2.0).

See CONTRIBUTING.md for dev setup and conventions, SECURITY.md for reporting vulnerabilities, and CHANGELOG.md for history.

Website: klopot.dev. Bugs and ideas go to Issues; anything else — questions, help with an installation, an integration — to contact@klopot.dev or the form on the site.


The team

Built by Stefan Maldaianu — product owner, operator and the person who gets paged at 02:00 — together with Claude (Anthropic), pair-programmer across architecture, code, audits, documentation and the Klopot brand.

Human judgement, machine stamina. The best team in the stack.

About

Self-hosted alerting and notification service: MQTT, webhooks, HTTP polling and Alertmanager feed rules that fire alerts to Telegram, ntfy, Gotify, Pushover, SMS, email, Web Push and webhooks — with incidents, escalation, quiet hours and an admin UI.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages