127 lines
5.1 KiB
Markdown
127 lines
5.1 KiB
Markdown
# Fluxer Admin Alerts
|
|
|
|
A small Python script that checks a Fluxer instance's Admin API for things an instance admin should look at, and sends an alert when something needs attention.
|
|
|
|
It is meant to run on a schedule (cron). Each run it remembers what it has already told you, so you only get alerts for new items, plus a reminder on a schedule until the item is cleared in the admin UI.
|
|
|
|
Alerts go to a Fluxer channel through a webhook. Other notifiers (for example Gotify) can be added later.
|
|
|
|
## What it checks
|
|
|
|
| Source (config name) | Admin API endpoint | Alerts when | Required ACL |
|
|
| --- | --- | --- | --- |
|
|
| `pending_reports` | `GET /v1/admin/reports?status=pending` | A report is waiting. Reminder if it is still open after `stale_after_hours`. Marked urgent when the reason is highest priority. | `report:view` |
|
|
| `pending_registrations` | `GET /v1/admin/instance/pending-registrations` | An account is waiting for approval. | `registration:review` |
|
|
| `discovery_applications` | `GET /v1/admin/discovery/applications` | A community is waiting for discovery approval. | `discovery:review` |
|
|
| `enforcement_review` | `GET /v1/admin/enforcement-decisions?review_queue=true` | An automated moderation decision needs a person to review it. | `enforcement:view` |
|
|
|
|
## Requirements
|
|
|
|
- Linux (tested on Debian)
|
|
- Python 3.11 or newer
|
|
- An Admin API key on your instance with the ACLs in the table above
|
|
- A Fluxer webhook URL for the channel that should receive alerts
|
|
|
|
## Install
|
|
|
|
These steps use a virtual environment (`.venv`), which is the supported way to run this project.
|
|
|
|
```sh
|
|
sudo apt install python3 python3-venv
|
|
|
|
cd /path/to/fluxer-admin-alerts
|
|
python3 -m venv .venv
|
|
. .venv/bin/activate
|
|
pip install -r requirements.txt
|
|
|
|
cp .env.example .env
|
|
cp config.example.toml config.toml
|
|
```
|
|
|
|
Then edit `.env` and `config.toml` (see below).
|
|
|
|
To run the tests:
|
|
|
|
```sh
|
|
python -m unittest discover -s tests
|
|
```
|
|
|
|
## Configure
|
|
|
|
There are two config files. Both are ignored by git, so your values stay on your machine.
|
|
|
|
### `.env`: URLs and secrets
|
|
|
|
| Variable | Description |
|
|
| --- | --- |
|
|
| `FLUXER_API_URL` | Base URL of the Fluxer API, including `/v1`. |
|
|
| `FLUXER_ADMIN_API_KEY` | Admin API key. |
|
|
| `ADMIN_UI_URL` | Base URL of your admin UI. Used to build links in alerts. |
|
|
| `FLUXER_WEBHOOK_URL` | Webhook URL for the alert channel. Required when the `fluxer` notifier is enabled. |
|
|
|
|
### `config.toml`: behaviour
|
|
|
|
| Setting | Default | Description |
|
|
| --- | --- | --- |
|
|
| `general.realert_hours` | `12` | Hours before an open item is alerted again. `0` turns repeats off. |
|
|
| `general.notify_cleared` | `true` | Send a message when an item is cleared. |
|
|
| `general.request_timeout` | `15` | Seconds to wait for each HTTP request. |
|
|
| `general.state_file` | `state.db` | Where the alert history is stored. |
|
|
| `general.notifiers` | `["fluxer"]` | Notifiers to use. |
|
|
| `sources.<name>.enabled` | `true` | Turn a source on or off. |
|
|
| `sources.pending_reports.stale_after_hours` | `48` | Hours a report can stay open before the reminder. |
|
|
|
|
## Admin API key
|
|
|
|
Create an Admin API key in the admin UI with these ACLs:
|
|
|
|
- `report:view`
|
|
- `registration:review`
|
|
- `discovery:review`
|
|
- `enforcement:view`
|
|
|
|
Fluxer only lets a key use ACLs that the account that owns it also has, so that account needs the same ACLs.
|
|
|
|
Give the key only what it needs. Remove a source from `config.toml` and drop its ACL if you do not want that check.
|
|
|
|
## Run
|
|
|
|
Check what would be sent, without sending anything or saving state:
|
|
|
|
```sh
|
|
.venv/bin/python -m fluxer_admin_alerts --dry-run
|
|
```
|
|
|
|
Run for real:
|
|
|
|
```sh
|
|
.venv/bin/python -m fluxer_admin_alerts
|
|
```
|
|
|
|
Use `-v` for debug logging. Exit code `0` means success, `1` means at least one source or notifier failed, and `2` means the config is wrong.
|
|
|
|
## Schedule with cron
|
|
|
|
Edit your crontab with `crontab -e` and add a line to run every hour:
|
|
|
|
```cron
|
|
0 * * * * cd /path/to/fluxer-admin-alerts && .venv/bin/python -m fluxer_admin_alerts >> alerts.log 2>&1
|
|
```
|
|
|
|
Replace `/path/to/fluxer-admin-alerts` with the folder you cloned into. `alerts.log` is ignored by git.
|
|
|
|
## How alerts work
|
|
|
|
- **New item:** alerted once, the first time it is seen.
|
|
- **Reports:** after `stale_after_hours` (48 by default) a "Still open" reminder is sent if the report is still pending.
|
|
- **Repeats:** an item still open after `realert_hours` (12 by default) is alerted again, until it is cleared.
|
|
- **Cleared:** when an item is no longer returned by the API (for example it was resolved in the admin UI), a "Cleared" message is sent if `notify_cleared` is on.
|
|
- **Failures:** if the Fluxer API or the webhook is unreachable, nothing is recorded for that run, so the alerts are sent on the next run. If one source fails, the others still run, and items from the failed source are not marked as cleared.
|
|
|
|
## Adding a notifier
|
|
|
|
Notifiers live in `fluxer_admin_alerts/notifiers/`. A notifier subclasses `Notifier`, implements `send(messages)`, raises `NotifierError` on failure, and is registered in `notifiers/__init__.py`. Then add its name to `KNOWN_NOTIFIERS` in `config.py` and read any settings it needs from `.env`.
|
|
|
|
## License
|
|
|
|
Beer-ware. See [LICENSE](LICENSE).
|