Skip to main content
Version: 0.4 · current

Architecture

ConceptReviewed October 11, 2026
Applies to:Excubius 0.4Roles: Entity admin, Super admin, Installer (Linux administrator)
PlansFree · Core · Pro · EnterpriseDeploymentSelf-hosted

Excubius runs as a small set of containers on one Linux server that you control. A read-only collector and the monitoring tools you already own feed one pipeline that turns everything into resources, states and alerts, stores it in one database and serves it to the web app, Slack, Jira and a public status page. This article explains each part, how a measurement becomes an alert, how the server is laid out and what is stored where.

The parts and how they connect​

PartWhat it does
CollectorRuns the checks of the catalog against your systems: T-SQL for SQL Server, HTTP and DNS for endpoints, certificates and domains, the Azure and Microsoft Graph APIs, and Wazuh searches. Windows over WinRM and Linux over SSH are experimental. It also polls the tools you own. It connects with credentials that have no write permission and keeps its results in a buffer while the server is busy or restarting
SourcesNew Relic, NinjaOne and Azure Monitor, each read by polling, by webhook or both. What they report joins the same pipeline as the collector's results, so their alerts reach the same inbox and the same channels
NormalizerTurns every input into the same three shapes: a resource, a check result or an alert. Resources are matched across sources by identifiers such as the Azure resource ID, the host name and the FQDN, so one server seen by three tools is one resource
Alert engineCompares each result with its effective thresholds, opens, escalates and resolves alerts, deduplicates them, groups them under a root cause, holds notifications during silences and maintenance windows, and works out the state of each resource
DatabasePostgreSQL 16 with TimescaleDB holds everything: configuration, resources, metrics, alerts with their timelines, findings and the audit log
API and web appThe API serves the web app and checks every request against your role on the entity it concerns. The web app runs in any current browser and installs on a phone or tablet. The public status page is built only from what administrators chose to publish
NotificationsSlack messages go out right after results are stored, and a background sweep every 15 seconds sends what had to wait. A slow or unavailable Slack never delays monitoring. Jira issues are created on request and followed until they are done

How a measurement becomes an alert​

  1. The collector runs a check when it is due and posts the result to the API over the server's internal network. A source reports through a poll or a webhook instead.
  2. The result is stored first, so nothing is lost if a later step fails. Its values are written to the metrics history.
  3. The alert engine compares the value with the effective thresholds of that check on that resource. When a condition holds for its whole for duration, it opens an alert, or updates the one already open for the same condition.
  4. The resource's state is recalculated, and the web app shows it on its next refresh.
  5. The notification step decides whether the change is worth a message, finds the channels through the entity tree and records every message on the alert's timeline.

Alerts and notifications explains steps 3 to 5 in detail, and Thresholds and baselines explains where the effective thresholds come from.

One server, six containers​

Everything runs on one server with Rocky Linux 9 or 10, or another Red Hat Enterprise Linux family system, on x86_64. The minimum is 2 vCPUs, 4 GiB of memory and 20 GiB of free disk. The containers run rootless with Podman under a service account, excubius by default, and start with the server. There is no source code on the server: a release is a set of container images plus a deployment bundle, installed and upgraded by the installer.

ContainerRole
proxyThe only container with open ports, 80 and 443. It ends TLS, sends requests to the web app or the API, and rate-limits webhooks
frontendServes the web app
backendThe API, the normalizer, the alert engine, notifications, Jira and the public status page
collectorThe collector and the polling of sources. It opens no port and receives only its own token and settings, never the database password or the key that encrypts stored secrets
certsIssues and renews the TLS certificate: Let's Encrypt, self-signed or your own
dbPostgreSQL 16 with TimescaleDB

The collector talks to the API over the server's internal network only: the proxy refuses the collector's routes from outside. Outbound, the server needs HTTPS to Slack, Jira and the APIs of your sources. The updates module also reads public build and advisory feeds, and falls back to the copies shipped with the release when the server cannot reach them. In Azure, give the server's managed identity read-only roles, such as Reader and Monitoring Reader, so the collector reads Azure without a stored secret.

tip

Point an external uptime monitor at https://<your host>/heartbeat. It answers ok while the server runs, so you hear about it when Excubius itself is down.

What is stored where​

DataWhereHow long
Entities, resources, checks, thresholds, users and rolesDatabaseUntil you change them
MetricsDatabase, in a TimescaleDB hypertable90 days
Alerts, findings, their timelines, seen-by and assignmentsDatabaseKept as history
Webhook payloads from sourcesDatabase30 days
Security score historyDatabaseOne snapshot an hour for 14 days, then one a day for 400 days
Audit logDatabaseKept
Credentials and source secretsDatabase, encrypted with a key that is stored only in the server's configuration fileUntil you replace or remove them
Server configuration: database password, session signing secret, encryption key, collector tokenThe .env file of the install directory, /opt/excubius by defaultGenerated once by the installer
TLS certificateA volume of the certs containerRenewed automatically when 30 days or less remain
Database backupsThe backups folder of the install directory: a dump every day at 02:30 server timeThe last 14 dumps

Secrets are write-only: once saved, nobody can read them back in the web app or through the API. A database dump alone reveals no secret, because the key is not in the database; for the same reason, keep a copy of the .env file with your backups, or the stored secrets of a restored database must be entered again. Copy the daily backups off the server with your usual server backup; Upgrade, back up and restore explains how to restore them.

Read-only by design​

Excubius detects, explains and suggests; it never changes a monitored system.

  • Monitoring logins and API credentials are created without write or install rights. A SQL Server login never needs sysadmin.
  • Security findings and update advisories carry a suggested action as text for a person to follow in a change window. Nothing is executed and nothing is installed.
  • Nothing is written to New Relic, NinjaOne, Azure, Microsoft Entra ID or Wazuh.
  • Deleting a resource in Excubius deletes its checks, metrics and alerts in Excubius only. The monitored system is not touched.

When something fails​

FailureWhat Excubius does
A source's API is downThe source turns stale and shows the error. Nothing is resolved from a failed poll, and no alert is invented
The collector cannot reach a resourceAfter three connection, sign-in or timeout failures in a row, the resource turns Critical with one Cannot reach alert, and the resource's other alerts wait behind it
The API or the database is briefly unavailableThe collector keeps its results and sends them later. A result sent twice is stored once
Slack is unavailableMonitoring carries on. The failed message is recorded on the alert and retried, three attempts in all
The Excubius server is downWebhooks sent meanwhile are lost. Sources in hybrid mode recover them at the next reconciliation