Skip to content
alerton

Projects

AlertOn (In-House Alert Management Tool)

AlertOn is a self-hosted alert bridge for ops teams running legacy or resource-constrained servers. Thin Node.js CLI agents push alerts and heartbeats to a small Docker control plane (Express API, React UI, PostgreSQL) without requiring Prometheus, ELK, Kafka, or a full observability stack on every host.

Node JS · PostgreSQl · React JS · Javascript · Linux · Docker

1.Overview

AlertOn centralizes incident signals from many servers into one authenticated web app. Engineers deploy a lightweight CLI on each host; the agent authenticates with a per-server API key, posts alerts, sends heartbeats, and can auto-resolve quiet fingerprints. Admins manage inventory (countries, applications, groups, servers, users), rotate agent keys, and review audit activity. Operators see group-scoped alerts and in-app notifications, not a separate mobile push network.

The product is intentionally not a competitor to Grafana, Prometheus, Loki/ELK, or Kafka-based alerting. Those platforms collect metrics, logs, and traces at scale. AlertOn fills a different gap: push-based alert ingest + lifecycle + RBAC UI on boxes that cannot (or should not) run a modern monitoring fleet, or as a companion for “legacy islands” next to an existing stack.

Security model:

  • Web UI: JWT after login; optional TOTP; account lock/unlock; password change / reset requests.
  • Agents: per-server X-API-Key (plaintext shown once on create/rotate; SHA-256 hashed at rest).

One React application serves both admin and operator workflows via role-based UI, not two separate portals.

3.Architecture

flowchart LR
  subgraph Agents["Agent hosts (legacy / constrained)"]
    S1["Server A"]
    S2["Server B"]
    S3["Server N"]
    CLI["Node CLI agent\n--agent / one-shot alert"]
    S1 --> CLI
    S2 --> CLI
    S3 --> CLI
  end

  subgraph Plane["Control plane (Docker Compose)"]
    API["Express REST API"]
    AUTH["JWT UI auth\n+ API-key ingest"]
    CORE["Alert lifecycle\nfingerprint · resolve · retention"]
    HB["Heartbeat / Live-Down"]
    DB[("PostgreSQL")]
    UI["React web app\nadmin + operator RBAC"]
    NOTE["In-app notifications"]
  end

  ADMIN["Administrators"]
  OPS["Operations users"]

  CLI -->|"HTTPS + X-API-Key\n(per server)"| API
  API --> AUTH
  AUTH --> CORE
  AUTH --> HB
  CORE --> DB
  HB --> DB
  CORE --> NOTE
  NOTE --> DB

  ADMIN --> UI
  OPS --> UI
  UI -->|"JWT Bearer"| API
  API --> DB
High level flow


4.Implementation

AlertOn is a modular monorepo:

Package: Role

alerton-backend : Express + Sequelize API, Umzug migrations, JWT + ingest auth

alerton-frontend: React (CRA) + MUI single app with admin/operator views

alerton-cli: Commander agent: alert, resolve flush, heartbeat --agent service mode

docs/: Deploy, admin, engineer, user, architecture guides




Backend. REST APIs cover login/TOTP/password flows, users (including lock/unlock), groups and permissions, countries/apps/servers, alert ingest and listing (server-side pagination), heartbeats, in-app notifications and prefs, access/password-reset requests, audit log, and dashboard summary. Alert processing uses message fingerprints so the same fault reasserts an open alert instead of creating noise; quiet fingerprints can resolve after a configured interval. Resolved alerts are pruned by retention (app → server → global days).




Frontend. One web UI: dashboard (active alerts + agents live/total), alerts (filters + paging), inventory, users/groups, access requests, audit, and settings (notification severity prefs, optional TOTP). Admins get clear/resolved tools and server agent key create/rotate (reveal-once).




CLI. On each monitored host: Node 18+, config.yaml with API URL, server_name, and that server’s key. Run one-shot alerts or node cli.js --agent as a Windows (NSSM/Task) or Linux (systemd) service no Docker required on the agent.




Data. Relational PostgreSQL (users, groups, servers, alerts, notifications, audit, requests) not document “collections.”

5.Results

  • Delivered a production-usable internal alert bridge for legacy/constrained hosts: Node-only agents, small three-service Compose control plane.
  • Replaced fragmented “email/script” noise with authenticated ingest, fingerprint lifecycle, group-scoped visibility, and audit.
  • Agent liveness without a metrics stack: heartbeats (default 15 minutes) and dashboard Live / Down / Unknown.
  • Security posture appropriate to the niche: bcrypt passwords, JWT UI sessions, optional TOTP, hashed per-server ingest keys, account lock.
  • Documented always-on install for Windows and Linux agents; public reference repo: github.com/diwakar767/LongShot.

6.Learnings

Building AlertOn reinforced that platform design for constrained environments is about deliberate non-goals: ship a reliable push path and RBAC UI rather than cloning Grafana. Practical takeaways included separating UI auth (JWT) from machine auth (per-host API keys), modeling alerts as a lifecycle (open / reassert / resolve) instead of append-only rows, and treating agent install (systemd/NSSM) as part of the product not an afterthought. It also clarified how to communicate a niche system honestly: complementary to modern observability stacks, not a drop-in replacement.