Nowlert CE

Infrastructure reports. Nowlert delivers.
Community Edition · free & open source · self-hosted

Self-hosted infrastructure notifications from SMTP, HTTP and Redfish to Teams, Slack, Discord and more.

Nowlert CE is the free, open-source, self-hosted edition of Nowlert. It receives infrastructure signals, normalizes vendor-specific events, applies deterministic routing, and delivers clear operational notifications through the tools and workflows teams already use.

Receive → Normalise → Route → Deliver

MIT · Docker-ready · Local SQLite · Same-origin WebUI

Quick Start · Supported integrations · Documentation · Releases

---

🚀 Quick Start

1. Clone and prepare configuration

git clone https://github.com/Theriark/nowlert-ce.git
cd nowlert-ce

cp .env.example .env
cp config/config.example.yaml config/config.yaml
mkdir -p logs/emails secrets state external-backups
chmod 600 .env config/config.yaml
chmod 700 logs logs/emails secrets state external-backups

Set NOWLERT_UID and NOWLERT_GID in .env to the numeric user/group that owns the mounted directories:

id -u
id -g

2. Validate and start

docker compose -f compose.production.yaml config
docker compose -f compose.production.yaml pull
docker compose -f compose.production.yaml up -d
docker compose -f compose.production.yaml ps
docker logs -f nowlert-ce

The default production image is:

theriark/nowlert-ce:3.1.3

3. Create the first administrator

On an empty platform database, the container log prints a short-lived, single-use setup token. Open the WebUI and use that token to choose the first administrator username and password.

There is no default password.

---

🚀 Project Status

What changed in v3.1.3

v3.1.3 is a documentation and discoverability patch release. It keeps schema 9, preserves the existing runtime contracts, and does not require a database migration from v3.1.2.

Highlights:

• adds practical Xen Orchestra → Discord and Xen Orchestra → Microsoft Teams guides;
• adds a direct homelab SMTP-ingestion guide without mailbox forwarding rules;
• adds Dell iDRAC Redfish and Zabbix HTTP/Event API routing guides;
• adds dedicated docs/guides/ and docs/integrations/ navigation indexes;
• keeps existing integration-document paths intact; and
• preserves the build-once immutable Development → Stage → Production Reference release model without rebuild.

See v3.1.3 release notes and the v3.1.3 QA checklist.

---

📸 Preview

v3.1.3 keeps the approved v3.1.0 visual design, so the existing screenshot set remains the current visual baseline. New screenshots are added only when the rendered UI or notification presentation materially changes.

Current WebUI

Notifications

More UI behavior is documented in the WebUI guide.

---

What is Nowlert?

Nowlert is an infrastructure operations platform that transforms system signals into clear, structured operational information and delivers it through the tools and workflows teams already use.

In Community Edition, that foundation is parser-driven and self-hosted. It accepts events from infrastructure products, converts them into one shared notification model, applies deterministic routes, and renders destination-aware notifications. The goal is not to replace monitoring, storage, virtualization, networking, backup, or hardware-management systems. The goal is to make the events they already emit easier to route, read, and act on.

Nowlert does not poll mailboxes, Microsoft Graph, Gmail, IMAP, or vendor infrastructure APIs. SMTP-capable systems send mail directly to Nowlert; webhook-capable systems post to authenticated HTTP endpoints; supported hardware controllers can submit Redfish Event Service notifications.

---

🦉 Why the name?

Nowlert combines now, an observant owl, and an actionable alert. The name reflects the product's purpose: receive infrastructure events, identify what matters, and deliver a clear notification while it is still useful.

Immediate. Readable. Actionable.

---

Why Nowlert?

Infrastructure products still report important events through a mixture of long HTML email, vendor-specific webhooks, and hardware event envelopes. Nowlert gives those events a consistent operational path.

---

✨ Features

Event ingestion

• native SMTP listener;
• authenticated HTTP Event API;
• dedicated vendor HTTP webhook endpoints;
• Redfish Event Service ingestion;
• optional SMTP STARTTLS and SMTP AUTH;
• bounded request and payload handling;
• parser-based source detection and normalization.

Routing

• database-authoritative routes;
• integration + input route identity;
• numeric priority with deterministic tie-breaking;
• host and event include/exclude patterns;
• included severity and status selection;
• fallback-only wildcard routes;
• duplicate-delivery suppression per destination;
• enable/disable controls without rewriting config.yaml.

Dedicated integration routes

Nowlert evaluates enabled routes for the detected integration first. A wildcard route is a true fallback, not an additional fan-out rule.

Fallback routes run only when needed

Fallback routes run only when no enabled dedicated route matches the event. This prevents a specific iDRAC, Zabbix, or other source event from also being sent through a generic fallback destination unless that is the only matching path.

Destinations

The platform supports:

• Discord;
• Microsoft Teams;
• Slack;
• generic webhooks;
• MQTT; and
• ntfy.

Destination credentials are write-only. Read APIs expose only safe metadata such as whether a secret is configured. Private destinations are owner-scoped; administrators may explicitly share destinations for route use.

Rich presentation

• source-aware Discord components;
• Microsoft Teams Adaptive Cards;
• severity/status styling;
• structured event, host/device, source, and time fields;
• packaged source artwork;
• explicit preview and test-delivery flows;
• bounded Microsoft Teams payload size with accurate accepted/delivered wording.

WebUI

The bundled same-origin WebUI provides:

• Dashboard/Overview analytics and routing flow;
• Sources/integration catalogue;
• Destinations;
• Routes;
• Event API tokens;
• Delivery History;
• Audit Log;
• Users;
• Inputs;
• Backups and Data tools;
• integration settings;
• regional preferences; and
• operational health/restart controls.

No default account exists. First startup creates a short-lived, single-use setup token so the operator chooses the first administrator credentials.

Platform state and backups

• SQLite schema 9;
• /nowlert/state persistent mount;
• owner-only secret files;
• verified private state snapshots;
• explicit restore safety snapshot;
• individual backup deletion;
• Local, NFS, and SMB backup targets;
• scheduled backup execution;
• credential-free portability export/import.

Security

• non-root production container;
• read-only root filesystem;
• dropped Linux capabilities;
• no-new-privileges;
• HttpOnly SameSite session cookies;
• optional Secure cookie mode;
• CSRF protection on unsafe session requests;
• source-scoped Event API tokens stored as hashes;
• write-only destination credentials;
• no credential values in audit or delivery history.

---

🔌 Supported Integrations

Integrations are packaged with the image. Inputs are the normalized transport used to receive the event.

Detailed setup guides are under docs/integrations/.

---

🎯 Project Goals

Nowlert is designed to:

1. normalize infrastructure events without replacing the systems that emit them;
2. keep routing deterministic and explainable;
3. keep credentials out of public configuration and read APIs;
4. remain practical for a single-node homelab while using production-quality security boundaries;
5. make deployment state, source commit, and released image traceable; and
6. keep documentation, tests, release metadata, and screenshots aligned with the shipped image.

---

🧩 Core Concepts

Integration

A built-in source family such as Xen Orchestra, Zabbix, or Dell iDRAC.

Input

The normalized transport: SMTP, HTTP, or Redfish.

Normalized event

The shared internal representation produced after source detection and parsing. It carries the event identity, source, title/message, severity/status, and bounded metadata used by routing and presentation.

Route

A database record that connects an integration/input contract to a destination. Routes may constrain hosts, events, severities, and statuses.

Destination

A configured output target such as Discord or Microsoft Teams. Public settings and secret credentials are separated.

Fallback route

A wildcard route evaluated only when no dedicated integration route matches.

Event API token

A source-scoped token accepted only by POST /api/v2/events. It is not a WebUI login credential and cannot manage platform resources.

---

🏗️ Architecture

Infrastructure product
        |
        | SMTP / HTTP / Redfish
        v
+-----------------------------+
| Input adapters              |
+-----------------------------+
        |
        v
+-----------------------------+
| Source detection + parsers  |
+-----------------------------+
        |
        v
+-----------------------------+
| Normalized event model      |
+-----------------------------+
        |
        v
+-----------------------------+
| Database-backed routing     |
| dedicated -> fallback       |
+-----------------------------+
        |
        v
+-----------------------------+
| Destination adapters        |
| Discord / Teams / ...       |
+-----------------------------+
        |
        v
 Collaboration / automation

The management plane uses the same local platform state:

WebUI <-> /api/v2 <-> SQLite + owner-scoped secret files
                    |
                    +-> audit history
                    +-> delivery history
                    +-> backups
                    +-> settings

---

⚡ Design Principles

Build once, promote the same image

A Development build produces an immutable GHCR digest. Stage, Production Reference, and stable release workflows reuse that digest; they do not rebuild from a branch or release tag.

Branches represent approved source state

• development is cumulative active work;
• stage is the source commit approved by the Stage promotion gate;
• main is fast-forwarded to that same Stage-approved commit before Production Reference and release finalization.

Configuration is split by responsibility

config.yaml contains process/bootstrap settings. WebUI-managed resources are stored in SQLite under /nowlert/state.

Secrets are write-only

Destination credentials and other sensitive values are not returned by normal read APIs, history, or audit views.

Failure is scoped

One damaged destination, route, or settings record should not make unrelated resources or pages unavailable.

---

⚙️ Configuration

The public configuration uses:

http:
  enabled: true
  host: 0.0.0.0
  port: 8080

api:
  enabled: true

platform:
  enabled: true
  state_dir: /nowlert/state
  configuration_model: platform_database_v1
  secure_cookies: false

webui:
  enabled: true
  public_url: ""
  enforce_https: false

config.yaml is intentionally limited to process bootstrap, listeners, transport security, state location, and WebUI publication settings.

Do not recreate legacy WebUI-managed YAML sections such as outputs, routing, api.tokens, notifications, presentation, home_assistant, redfish, platform.backups, or webui.language in a fresh v3.1.3 configuration.

See Current configuration model.

---

📬 SMTP Configuration

SMTP can be used directly by products such as Xen Orchestra, QNAP, and TrueNAS. STARTTLS and SMTP AUTH are optional and disabled by default.

For an untrusted network, enable TLS before enabling SMTP AUTH. Store passwords in environment variables or mounted secrets rather than tracked files.

See SMTP security.

---

🔄 Example Flow

A Zabbix webhook arrives over HTTP:

Zabbix
  -> HTTP input
  -> Zabbix parser
  -> normalized event
  -> enabled Zabbix (HTTP) routes
  -> host/event/severity/status filters
  -> selected destination
  -> Discord / Teams / webhook / ...

If no dedicated Zabbix route matches, Nowlert may then evaluate an enabled Fallback (HTTP) route.

The same routing model is used for SMTP and Redfish events.

---

🛡️ Production Deployment

The supplied production Compose definition:

• runs as the configured numeric UID/GID;
• drops capabilities;
• prevents privilege escalation;
• uses a read-only root filesystem;
• provides bounded temporary storage; and
• persists only the configured state, logs, configuration, and backup mounts.

Recommended persistent paths:

Back up config, state, and external secrets as one matched set before an upgrade or rollback.

See Deployment and Platform state.

---

🔐 Browser and API Security

Use direct HTTP only on a trusted private network. Internet-facing or otherwise untrusted access should terminate TLS at a trusted reverse proxy and enable:

platform:
  secure_cookies: true

webui:
  public_url: "https://nowlert.example.com"
  enforce_https: true

Do not cache /api/v2 responses and do not expose secret-bearing environment or mount contents through the proxy.

See Platform API.

---

💾 Backup, Restore, and Portability

There are two different safety mechanisms:

1. Private state backup — SQLite + owner-scoped secret files + integrity manifest. Use for recovery and rollback.
2. Portable JSON export — credential-free resource metadata. Use for migration and configuration transfer, not disaster recovery.

Administrators can create, verify, restore, and delete private state snapshots. A restore creates a safety snapshot first and revokes browser sessions after a successful swap.

See Data portability and migration.

---

🚢 Release and Promotion Model

The CE release chain is intentionally immutable:

development
   |
   | CI + Development Image
   v
Development exact digest
   |
   | Promote CE to Stage (no rebuild)
   v
stage branch == approved source SHA
   |
   | fast-forward main to stage SHA
   v
main == stage == approved source SHA
   |
   | Promote CE to Production Reference (no rebuild)
   v
Production Reference exact digest
   |
   | release/finalization gates
   v
version tag + stable aliases for the same digest

The promotion workflows reject a source SHA that does not match the expected environment branch or desired-state ledger. Stable registry aliases are created from the already-approved immutable image; they do not rebuild the application from the release tag.

Operational workflow details are in Deployment.

---

🗺️ Roadmap

Current priorities are intentionally conservative:

• keep the stable image, documentation, screenshots, and examples synchronized;
• broaden real-system compatibility validation;
• preserve schema migration and rollback coverage;
• keep the production container non-root and capability-minimal;
• expand integrations and destinations only behind explicit contracts/tests;
• improve drift detection and release evidence.

See the full roadmap.

---

📚 Documentation

Start with the documentation index.

Core guides:

• Current configuration model
• Deployment
• WebUI
• Integrations and inputs
• Platform routing and delivery
• Platform outputs
• Platform API
• Platform state
• Data portability and migration
• SMTP security
• Presentation contract
• Roadmap

Historical release notes and acceptance checklists remain under docs/releases/ and docs/*-acceptance-checklist.md. They describe the versions they were written for and are intentionally not rewritten as current guidance.

---

🤝 Contributing

Contributions should keep behavior, tests, and documentation aligned.

Before opening a pull request:

python -m pip install -r requirements-dev.txt
python -m pytest -q
python tools/validate_current_documentation.py

For user-visible changes, update the relevant current guide and add or refresh screenshots when the UI actually changed. Never use screenshots containing credentials, token values, private URLs, or personal data.

See CONTRIBUTING.md.

---

📄 License

Nowlert CE is released under the MIT License. See LICENSE.

Powered by Theriark.