mirror of
https://github.com/moan0s/alertbot.git
synced 2024-09-30 01:45:35 +00:00
Compare commits
No commits in common. "ec4456555804478d5a9765a93d6361cb1b466b9a" and "884adac459c4a7c9b6fb1999f65486722bed71da" have entirely different histories.
ec44565558
...
884adac459
@ -1,7 +1,3 @@
|
|||||||
# April 2023
|
|
||||||
|
|
||||||
Raw mode defaults to unordered list, for improved readability.
|
|
||||||
|
|
||||||
# March 2023
|
# March 2023
|
||||||
|
|
||||||
Change `!url` to display the full webhook url not just the base
|
Change `!url` to display the full webhook url not just the base
|
||||||
|
73
README.md
73
README.md
@ -3,52 +3,50 @@
|
|||||||
# 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.
|
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
|
||||||
|
join the [Alertbot room on matrix](https://matrix.to/#/#alertbot:hyteck.de)
|
||||||
|
|
||||||
## Getting Started
|
# 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)
|
||||||
|
|
||||||
## Self-host an Instance
|
## OPTION 2: Selfhost alertbot
|
||||||
|
|
||||||
**Prerequisites:**
|
**Prerequisites:**
|
||||||
* A Matrix server where you have access to a maubot instance
|
* 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
|
||||||
* 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
|
||||||
|
|
||||||
**Build the Bot**
|
**Getting the code**
|
||||||
|
|
||||||
The bot is built using the maubot command line tool `mbc`, you can either build it locally or remotely.
|
Clone this repository to your local computer and install maubot to have access to the maubot CLI
|
||||||
|
|
||||||
Build it locally, and afterwards navigate to the Maubot Administration Interface and upload the .mpb file.
|
|
||||||
```shell
|
```shell
|
||||||
pip install maubot
|
|
||||||
git clone https://github.com/moan0s/alertbot
|
git clone https://github.com/moan0s/alertbot
|
||||||
cd alertbot
|
cd alertbot
|
||||||
mbc build
|
pip install maubot
|
||||||
```
|
```
|
||||||
|
|
||||||
It's possible to upload the build to you maubot instance from the CLI. This is especially helpful when developing.
|
**Login to your maubot instance**
|
||||||
First login to your instance, then add the `-u` flag to upload after build.
|
|
||||||
```shell
|
```shell
|
||||||
mbc login
|
mbc login
|
||||||
|
```
|
||||||
|
|
||||||
|
**Build&Upload the plugin**
|
||||||
|
|
||||||
|
```shell
|
||||||
mbc build -u
|
mbc build -u
|
||||||
```
|
```
|
||||||
|
|
||||||
**Configure the Bot**
|
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`.
|
||||||
|
|
||||||
Next, once the plugin is installed, set up a [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.
|
|
||||||
|
|
||||||
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`.
|
|
||||||
|
|
||||||
## Setup Alertmanager
|
# 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`):
|
||||||
@ -70,13 +68,39 @@ 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)
|
||||||
|
|
||||||
## Send Test Alerts
|
|
||||||
|
# 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
|
||||||
|
e.g. webbhook.example.com and configure nginx as reverse proxy for port 4242 for this domain.
|
||||||
|
|
||||||
|
## Connect
|
||||||
|
|
||||||
|
Run the local server and connect via (29316 is the local maubot port)
|
||||||
|
`ssh -N -R 4242:localhost:29316 webhook.example.com`
|
||||||
|
|
||||||
|
## Send some data with
|
||||||
|
|
||||||
Use an example from the `alert_examples/` to test your setup
|
Use an example from the `alert_examples/` to test your setup
|
||||||
```shell
|
```shell
|
||||||
@ -86,6 +110,3 @@ 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)
|
|
||||||
|
Loading…
Reference in New Issue
Block a user