tobast/matrix-alertbot
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

update readme

Browse source
This commit is contained in:
HgO 2022-08-13 13:33:14 +02:00
parent 6903dd383e
commit d9aa9601bf
4 changed files with 73 additions and 186 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

74
CONTRIBUTING.md
View file

@ -9,57 +9,6 @@ See the
[Install the dependencies section of SETUP.md](SETUP.md#install-the-dependencies) [Install the dependencies section of SETUP.md](SETUP.md#install-the-dependencies)
for help setting up a running environment for the bot. for help setting up a running environment for the bot.
If you would rather not or are unable to run docker, the following instructions
will explain how to install the project dependencies natively.
#### Install libolm
You can install [libolm](https://gitlab.matrix.org/matrix-org/olm) from source,
or alternatively, check your system's package manager. Version `3.0.0` or
greater is required.
**(Optional) postgres development headers**
By default, the bot uses SQLite as its storage backend. This is fine for a
few hundred users, but if you plan to support a much higher volume
of requests, you may consider using Postgres as a database backend instead.
If you want to use postgres as a database backend, you'll need to install
postgres development headers:
Debian/Ubuntu:
```
sudo apt install libpq-dev libpq5
```
Arch:
```
sudo pacman -S postgresql-libs
```
#### Install Python dependencies
Create and activate a Python 3 virtual environment:
```
virtualenv -p python3 env
source env/bin/activate
```
Install python dependencies:
```
pip install -e .
```
(Optional) If you want to use postgres as a database backend, use the following
command to install postgres dependencies alongside those that are necessary:
```
pip install ".[postgres]"
```
### Development dependencies ### Development dependencies
@ -67,7 +16,7 @@ There are some python dependencies that are required for linting/testing etc.
You can install them with: You can install them with:
``` ```
pip install -e ".[dev]" pip install -U -r requirements.txt
``` ```
## Code style ## Code style
@ -85,12 +34,27 @@ the linting CI happy:
./scripts-dev/lint.sh ./scripts-dev/lint.sh
``` ```
## Testing
Run the tests with the following:
```
pytest .
```
Code coverage can be generated with:
```
coverage run --source matrix_alertbot -p -m pytest
```
Then, run either `coverage html` or `coverage lcov` to generate the report.
For html report, the results can be found in `htmlcov` directory.
## What to work on ## What to work on
Take a look at the [issues Take a look at the [issues
list](https://github.com/anoadragon453/nio-template/issues). What list](https://git.domainepublic.net/Neutrinet/matrix-alertbot/-/issues). What
feature would you like to see or bug do you want to be fixed? feature would you like to see or bug do you want to be fixed?
If you would like to talk any ideas over before working on them, you can reach If you would like to talk any ideas over before working on them, you can reach
me at [@andrewm:amorgan.xyz](https://matrix.to/#/@andrewm:amorgan.xyz) us on our [Mattermost channel](https://chat.neutrinet.be/neutrinet/channels/hub-dev).
on matrix.

6
README.md
View file

@ -13,7 +13,9 @@ Features include:
## Getting started ## Getting started
See [SETUP.md](SETUP.md) for how to setup and run the template project. See [SETUP.md](SETUP.md) for how to setup and run the bot.
See [CONTRIBUTING.md](CONTRIBUTING.md) for how to contribute to the project.
## Project structure ## Project structure
@ -30,6 +32,6 @@ run `pip install -e .` in the project's root directory.
[PyPI](https://pypi.org)) and `setup.cfg` just contains some configuration [PyPI](https://pypi.org)) and `setup.cfg` just contains some configuration
options for linting tools. options for linting tools.
`sample.config.yaml` is a sample configuration file. You should copy this file to `config.yaml`, then edit it according to `config.sample.yaml` is a sample configuration file. You should copy this file to `config.yaml`, then edit it according to
your needs. Be sure never to check the edited `config.yaml` into source control your needs. Be sure never to check the edited `config.yaml` into source control
since it'll likely contain sensitive details such as passwords! since it'll likely contain sensitive details such as passwords!

105
SETUP.md
View file

@ -1,6 +1,6 @@
# Setup # Setup
nio-template is a sample repository of a working Matrix bot that can be taken Matrix AlertBot is a sample repository of a working Matrix bot that can be taken
and transformed into one's own bot, service or whatever else may be necessary. and transformed into one's own bot, service or whatever else may be necessary.
Below is a quick setup guide to running the existing bot. Below is a quick setup guide to running the existing bot.
@ -10,12 +10,12 @@ There are two paths to installing the dependencies for development.
### Using `docker-compose` ### Using `docker-compose`
It is **recommended** to use Docker Compose to run the bot while Docker Compose is the easiest way to run the bot with all the necessary dependencies handled for you.
developing, as all necessary dependencies are handled for you. After
installation and ensuring the `docker-compose` command works, you need to: After installation and ensuring the `docker-compose` command works, you need to:
1. Create a data directory and config file by following the 1. Create a data directory and config file by following the
[docker setup instructions](docker#setup). [docker setup instructions](docker/README.md#setup).
2. Create a docker volume pointing to that directory: 2. Create a docker volume pointing to that directory:
@ -26,13 +26,7 @@ installation and ensuring the `docker-compose` command works, you need to:
--opt device="/path/to/data/dir" data_volume --opt device="/path/to/data/dir" data_volume
``` ```
Run `docker/start-dev.sh` to start the bot. Run `docker-compose up --build` to start the bot.
**Note:** If you are trying to connect to a Synapse instance running on the
host, you need to allow the IP address of the docker container to connect. This
is controlled by `bind_addresses` in the `listeners` section of Synapse's
config. If present, either add the docker internal IP address to the list, or
remove the option altogether to allow all addresses.
### Running natively ### Running natively
@ -45,33 +39,20 @@ You can install [libolm](https://gitlab.matrix.org/matrix-org/olm) from source,
or alternatively, check your system's package manager. Version `3.0.0` or or alternatively, check your system's package manager. Version `3.0.0` or
greater is required. greater is required.
**(Optional) postgres development headers** #### Deploy Alertmanager and Prometheus
By default, the bot uses SQLite as its storage backend. This is fine for a few Matrix AlertBot requires an Alertmanager instance to manage silences, receive alerts from it, etc. You can follow install instructions on the [Alertmanager website](https://prometheus.io/docs/alerting/latest/alertmanager).
hundred users, but if you plan to support a much higher volume of requests, you
may consider using Postgres as a database backend instead.
If you want to use postgres as a database backend, you'll need to install Prometheus is also required in order to setup a set of rules that will trigger alerts. You can follow install instructions on the [Prometheus website](https://prometheus.io/docs/prometheus/latest/getting_started/)
postgres development headers:
Debian/Ubuntu: Sample configs are available in the `docker` directory.
```
sudo apt install libpq-dev libpq5
```
Arch:
```
sudo pacman -S postgresql-libs
```
#### Install Python dependencies #### Install Python dependencies
Create and activate a Python 3 virtual environment: Create and activate a Python 3 virtual environment:
``` ```
virtualenv -p python3 env virtualenv -p python3 .venv
source env/bin/activate source env/bin/activate
``` ```
@ -81,11 +62,11 @@ Install python dependencies:
pip install -e . pip install -e .
``` ```
(Optional) If you want to use postgres as a database backend, use the following (Optional) If you want to send alert to encrypted rooms, use the following
command to install postgres dependencies alongside those that are necessary: command to install olm dependencies alongside those that are necessary:
``` ```
pip install -e ".[postgres]" pip install -e ".[e2e]"
``` ```
## Configuration ## Configuration
@ -93,28 +74,11 @@ pip install -e ".[postgres]"
Copy the sample configuration file to a new `config.yaml` file. Copy the sample configuration file to a new `config.yaml` file.
``` ```
cp sample.config.yaml config.yaml cp config.sample.yaml config.yaml
``` ```
Edit the config file. The `matrix` section must be modified at least. Edit the config file. The `matrix` section must be modified at least.
#### (Optional) Set up a Postgres database
Create a postgres user and database for matrix-reminder-bot:
```
sudo -u postgresql psql createuser nio-template -W # prompts for a password
sudo -u postgresql psql createdb -O nio-template nio-template
```
Edit the `storage.database` config option, replacing the `sqlite://...` string with `postgres://...`. The syntax is:
```
database: "postgres://username:password@localhost/dbname?sslmode=disable"
```
See also the comments in `sample.config.yaml`.
## Running ## Running
### Docker ### Docker
@ -126,7 +90,7 @@ Refer to the docker [run instructions](docker/README.md#running).
Make sure to source your python environment if you haven't already: Make sure to source your python environment if you haven't already:
``` ```
source env/bin/activate source .venv/bin/activate
``` ```
Then simply run the bot with: Then simply run the bot with:
@ -135,11 +99,6 @@ Then simply run the bot with:
matrix-alertbot matrix-alertbot
``` ```
You'll notice that "matrix-alertbot" is scattered throughout the codebase. When
it comes time to modifying the code for your own purposes, you are expected to
replace every instance of "matrix-alertbot" and its variances with your own
project's name.
By default, the bot will run with the config file at `./config.yaml`. However, an By default, the bot will run with the config file at `./config.yaml`. However, an
alternative relative or absolute filepath can be specified after the command: alternative relative or absolute filepath can be specified after the command:
@ -151,23 +110,39 @@ matrix-alertbot other-config.yaml
Invite the bot to a room and it should accept the invite and join. Invite the bot to a room and it should accept the invite and join.
By default nio-template comes with an `echo` command. Let's test this now. Matrix AlertBot will process any message starting with the prefix defined in the config. By default, this prefix is `!alert`. Let's test this now.
After the bot has successfully joined the room, try sending the following After the bot has successfully joined the room, try sending the following
in a message: in a message:
``` ```
!c echo I am a bot! !alert help
``` ```
The message should be repeated back to you by the bot. The bot should reply with an help message, explaining how to handle alerts.
## Going forwards When an alert is triggered, the bot will send it to the room.
You can manage silences for this alert either by replying to the message,
or by reacting with certain emojis.
Congratulations! Your bot is up and running. Now you can modify the code, For instance, if you reply to the alert with:
re-run the bot and see how it behaves. Have fun!
```
!alert ack
```
This will create a silence for this alert until it is resolved.
You can at any moment reply to the alert with the following to remove the
silence:
```
!alert unack
```
Removing a reaction to an alert will also remove the silence.
## Troubleshooting ## Troubleshooting
If you had any difficulties with this setup process, please [file an If you had any difficulties with this setup process, please [file an
issue](https://github.com/anoadragon453/nio-template/issues]) or come talk issue](https://git.domainepublic.net/Neutrinet/matrix-alertbot/-/issues) or come talk
about it in [the matrix room](https://matrix.to/#/#nio-template). about it in [the Mattermost channel](https://chat.neutrinet.be/neutrinet/channels/hub-dev).

74
docker/README.md
View file

@ -21,7 +21,7 @@ persist across container restarts.
### Creating a config file ### Creating a config file
Copy `sample.config.yaml` to a file named `config.yaml` inside of your newly Copy `config.sample.yaml` to a file named `config.yaml` inside of your newly
created `data` directory. Fill it out as you normally would, with a few minor created `data` directory. Fill it out as you normally would, with a few minor
differences: differences:
@ -30,31 +30,11 @@ differences:
`/data/store`. There is no need to create this directory yourself, it will be `/data/store`. There is no need to create this directory yourself, it will be
created on startup if it does not exist. created on startup if it does not exist.
* Choose whether you want to use SQLite or Postgres as your database backend. * The bot cache directory should reside inside of the data directory as well,
Postgres has increased performance over SQLite, and is recommended for so that alerts and silences related informations are not wiped on container
deployments with many users. restart. Change it from the default to `/data/cache`.
There is no need to create this directory yourself, it will be created on
If using SQLite, ensure your database file is startup if it does not exist.
stored inside the `/data` directory:
```
database: "sqlite:///data/bot.db"
```
If using postgres, point to your postgres instance instead:
```
database: "postgres://username:password@postgres/matrix-alertbot?sslmode=disable"
```
**Note:** a postgres container is defined in `docker-compose.yaml` for your convenience.
If you would like to use it, set your database connection string to:
```
database: "postgres://postgres:somefancypassword@postgres/postgres?sslmode=disable"
```
The password `somefancypassword` is defined in the docker compose file.
Change any other config values as necessary. For instance, you may also want to Change any other config values as necessary. For instance, you may also want to
store log files in the `/data` directory. store log files in the `/data` directory.
@ -70,56 +50,22 @@ docker volume create \
--opt device="/path/to/data/dir" matrix-alertbot --opt device="/path/to/data/dir" matrix-alertbot
``` ```
Optional: If you want to use the postgres container defined in
`docker-compose.yaml`, start that first:
```
docker-compose up -d postgres
```
Start the bot with: Start the bot with:
``` ```
docker-compose up matrix-alertbot docker-compose up --build
``` ```
This will run the bot and log the output to the terminal. You can instead run This will run the bot and log the output to the terminal. You can instead run
the container detached with the `-d` flag: the container detached with the `-d` flag:
``` ```
docker-compose up -d matrix-alertbot docker-compose up -d --build
``` ```
(Logs can later be accessed with the `docker logs` command). (Logs can later be accessed with the `docker-compose logs` command).
This will use the `latest` tag from This will build an optimized, production-ready container.
[Docker Hub](https://hub.docker.com/neutrinet/matrix-alertbot).
If you would rather run from the checked out code, you can use:
```
docker-compose up local-checkout
```
This will build an optimized, production-ready container. If you are developing
instead and would like a development container for testing local changes, use
the `start-dev.sh` script and consult [CONTRIBUTING.md](../CONTRIBUTING.md).
**Note:** If you are trying to connect to a Synapse instance running on the
host, you need to allow the IP address of the docker container to connect. This
is controlled by `bind_addresses` in the `listeners` section of Synapse's
config. If present, either add the docker internal IP address to the list, or
remove the option altogether to allow all addresses.
## Updating
To update the container, navigate to the bot's `docker` directory and run:
```
docker-compose pull matrix-alertbot
```
Then restart the bot.
## Systemd ## Systemd