Quickstart¶
One machine, no account and no model key. In six steps you will start Paeon, send it an alert, watch it become an incident, and open the console. Nothing leaves your machine: without a rules file that enables a stage, Paeon calls no model.
You need Python 3.12 or later and uv.
Running Prometheus and Docker already?
The Prometheus quickstart starts a small compose project with Prometheus, Alertmanager and a demo service you break on purpose, and goes as far as a first investigated alert.
1. Get it¶
2. Configure the minimum¶
Paeon needs one secret, the token your alert senders present. Generate it into .env:
And a rules file that turns the console on:
3. Start it¶
It listens on 127.0.0.1:8080 and keeps its event log in paeon.sqlite. Leave it running and
open a second terminal in the same folder.
4. Send a first alert¶
Load the token in the second terminal:
Then post an alert the way Alertmanager would:
curl -X POST http://127.0.0.1:8080/ingest/alertmanager -H "Authorization: Bearer $PAEON_INGEST_TOKEN" -H 'Content-Type: application/json' -d '{"alerts": [{"status": "firing", "fingerprint": "demo-disk-full", "labels": {"alertname": "DiskFull", "severity": "warning", "instance": "server-1"}, "annotations": {"summary": "/ is 95 % full"}}]}'
Paeon answers {"alerts":1,"changes":1}: one alert received, one state change recorded.
5. See the incident¶
One line of JSON: incident 1, open, on server-1, with the alert attached. Now open the
console at http://127.0.0.1:8080/ui: the incident is in the Open group, and its page shows
the record of what happened so far.
Keep it local
The console has no login. On your own machine, bound to 127.0.0.1, that is fine. On a
server it belongs behind a reverse proxy that authenticates: see the console.
6. Resolve it¶
Send the same alert with resolved:
curl -X POST http://127.0.0.1:8080/ingest/alertmanager -H "Authorization: Bearer $PAEON_INGEST_TOKEN" -H 'Content-Type: application/json' -d '{"alerts": [{"status": "resolved", "fingerprint": "demo-disk-full", "labels": {"alertname": "DiskFull", "severity": "warning", "instance": "server-1"}, "annotations": {"summary": "/ is 95 % full"}}]}'
The incident moves to Resolved. Every step you just took is one line of the event log:
What you have, and what is next¶
You have the recording half of Paeon: alerts in, incidents out, a log of everything. No model was called and nothing was sent anywhere. From here, each step is a decision of yours:
| You want | Go to |
|---|---|
| Your real alerts in it | Connect your alerts: uptime-kuma, Alertmanager, Grafana, OpenObserve, Gatus, Zabbix and others |
| A model to say whether an alert is noise | triage in Configuration: one cheap call per incident, in shadow mode |
| A root cause with evidence on your phone | investigation in Configuration, and what it sends in Privacy and safety |
| Paeon to fix things after your Go | Acting: a second process, a closed catalog, and a decision of yours |
| It running for real | The hardened compose file: read-only root filesystem, non-root, secrets as files, Docker through a proxy limited to GET |
If it does not work¶
| Symptom | Cause |
|---|---|
paeon serve exits at once |
PAEON_INGEST_TOKEN is missing or shorter than 24 characters. The message says so. |
curl answers 401 |
The token in this terminal is not the one the server started with: run the set -a line again. |
/ui answers 404 |
ui.enabled is not set in the rules file Paeon reads: check PAEON_CONFIG in .env. |
| Port 8080 is taken | Add PAEON_PORT=8090 to .env and use that port in the commands. |