Matrix-Mirrors/maubot-alertbot
1
0
Fork 0
mirror of https://github.com/moan0s/alertbot.git synced 2024-10-01 06:25:35 -04:00
Code Issues Packages Projects Releases Wiki Activity

Update README.md

Browse Source
This commit is contained in:
spatterlight 2023-04-27 16:43:37 +00:00 committed by GitHub
parent 884adac459
commit 42d95c7c9d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 21 additions and 43 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

64
README.md
View File

@ -3,50 +3,41 @@
# Alertbot # Alertbot
This bot uses the webhook functionality of monitoring/alerting solutions like Grafana or Alertmanager to forward alerts to matrix rooms. This bot uses the webhook functionality of monitoring/alerting solutions like Grafana or Alertmanager to forward alerts to matrix rooms.
This means that you no longer have to use E-Mail or Slack to receive alerts. See the setup below for how to use it or This means that you no longer have to use E-Mail or Slack to receive alerts.
join the [Alertbot room on matrix](https://matrix.to/#/#alertbot:hyteck.de)
# Getting Started You can either [invite](#invite-the-official-instance) an official instance of the bot, or [self-host](#self-host-an-instance) it on your own matrix server.
## OPTION 1: Use provided alertbot ## Invite the Official Instance
* Create a Matrix room and invite @alertbot:hyteck.de * Create a Matrix room and invite @alertbot:hyteck.de
* Send `!url` to the room. The bot will answer with the webhook URL * Send `!url` to the room. The bot will answer with the webhook URL
* Put the Webhook URL into your monitoring solution (see below) * Put the Webhook URL into your monitoring solution (see below)
## OPTION 2: Selfhost alertbot ## Self-host an Instance
**Prerequisites:** **Prerequisites:**
* A Matrix server where you have access to a maubot instance: Please [refer to the docs](https://docs.mau.fi/maubot/usage/setup/index.html) for setting up one * A Matrix server where you have access to a maubot instance
* Refer to the [docs](https://docs.mau.fi/maubot/usage/setup/index.html) for setting up one
* or use [spantaleev/matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/docs/configuring-playbook-bot-matrix-registration-bot.md) which has built-in maubot support
* An instance of alertmanager or grafana or a similar alerting program that is able to send webhooks * An instance of alertmanager or grafana or a similar alerting program that is able to send webhooks
**Getting the code** **Build the Bot**
Clone this repository to your local computer and install maubot to have access to the maubot CLI Clone this repository and build it into a maubot plugin file (.mbp). Navigate to the Maubot Administration Interface and upload the .mpb file.
```shell ```shell
git clone https://github.com/moan0s/alertbot git clone https://github.com/moan0s/alertbot
cd alertbot cd alertbot
pip install maubot pip install maubot
mbc build
``` ```
**Login to your maubot instance** **Configure the Bot**
```shell Next, once the plugin is installed, set up an [client](https://docs.mau.fi/maubot/usage/basic.html#creating-clients) and then create an [instance](https://docs.mau.fi/maubot/usage/basic.html#creating-instances) which connects the client and plugin.
mbc login
```
**Build&Upload the plugin** Finally, invite the bot to an encrypted room where alerts should be sent and query the bot for the room id with the command `!roomid`.
```shell ## Setup Alertmanager
mbc build -u
```
You now have the plugin installed. Now you have to set up an instance of the bot in the maubot manager and invite it to
the room where the alerts should be sent. Also find out the room id by asking the bot for it with `!roomid`.
# Setup Alertmanager
This configuration will send all your alerts to the room `!zOcbWjsWzdREnihgeC:example.com` (if the bot has access to it). This configuration will send all your alerts to the room `!zOcbWjsWzdREnihgeC:example.com` (if the bot has access to it).
Put in your own room-id (`!roomid`) behind the webhook base url (`!url`): Put in your own room-id (`!roomid`) behind the webhook base url (`!url`):
@ -68,39 +59,23 @@ route:
``` ```
## Setup Grafana
# Setup Grafana
The grafana setup is fairly simple and can be used to forward grafana alerts to matrix. The grafana setup is fairly simple and can be used to forward grafana alerts to matrix.
![Screenshot of the Grafana Setup](assets/grafana.png) ![Screenshot of the Grafana Setup](assets/grafana.png)
## Run Locally
# Test your setup
It can be a bit annoying to trigger an alert (e.g. by shutting down a server) to test if your configuration is right and if the bot works as intended.
Therefore, you find a few example alerts in `alert_examples/` which allow you to test the bot.
Use them with the following command (but adjust the webhook URL):
```bash
curl --header "Content-Type: application/json" \
--request POST \
--data "@alert_examples/data.json" \
https://webhook.example.com/_matrix/maubot/plugin/maubot/webhook/!zOcbWjsWzdREnihreC:example.com
```
# Local testing Setup
You might want to test the bot on your local machine but send webhooks to a public server. To do that use a domain You might want to test the bot on your local machine but send webhooks to a public server. To do that use a domain
e.g. webbhook.example.com and configure nginx as reverse proxy for port 4242 for this domain. e.g. webbhook.example.com and configure nginx as reverse proxy for port 4242 for this domain.
## Connect **Connect**
Run the local server and connect via (29316 is the local maubot port) Run the local server and connect via (29316 is the local maubot port)
`ssh -N -R 4242:localhost:29316 webhook.example.com` `ssh -N -R 4242:localhost:29316 webhook.example.com`
## Send some data with ## Send Test Alerts
Use an example from the `alert_examples/` to test your setup Use an example from the `alert_examples/` to test your setup
```shell ```shell
@ -110,3 +85,6 @@ curl --header "Content-Type: application/json" \
https://webhook.example.com/_matrix/maubot/plugin/maubot/webhook/!zOcbWjsWzdREnihreC:example.com https://webhook.example.com/_matrix/maubot/plugin/maubot/webhook/!zOcbWjsWzdREnihreC:example.com
``` ```
## Matrix Room
This project has a dedicated [chat room](https://matrix.to/#/#alertbot:hyteck.de)