mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2025-02-12 01:58:58 +01:00
Compare commits
1 Commits
62869ac9ff
...
0277dc2080
| Author | SHA1 | Date | |
|---|---|---|---|
|
0277dc2080 |
@ -4,48 +4,23 @@ The playbook can install and configure the [matrix-alertmanager-receiver](https:
|
||||
|
||||
See the project's [documentation](https://github.com/metio/matrix-alertmanager-receiver/blob/main/README.md) to learn what it does and why it might be useful to you.
|
||||
|
||||
At the moment, **setting up this service's bot requires some manual actions** as described below in [Account and room preparation](#account-and-room-preparation).
|
||||
|
||||
This service is meant to be used with an external [Alertmanager](https://prometheus.io/docs/alerting/latest/alertmanager/) instance. It's **not** meant to be integrated with the [Prometheus & Grafana stack](./configuring-playbook-prometheus-grafana.md) installed by this playbook, because the Alertmanager component is not installed by it.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
### Register the bot account
|
||||
|
||||
This service uses a bot (with a username specified in `matrix_alertmanager_receiver_config_matrix_user_id_localpart`) for delivering messages.
|
||||
|
||||
The playbook does not automatically create users for you. You **need to register the bot user manually** before setting up the bot.
|
||||
|
||||
Choose a strong password for the bot. You can generate a good password with a command like this: `pwgen -s 64 1`.
|
||||
|
||||
You can use the playbook to [register a new user](registering-users.md):
|
||||
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.alertmanager.receiver password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user
|
||||
```
|
||||
|
||||
### Get an access token
|
||||
|
||||
The bot requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md).
|
||||
|
||||
### Join to rooms as the bot manually
|
||||
|
||||
ℹ️ **This bot does not accept room invitations automatically**. To deliver messages to rooms, the bot must be joined to all rooms manually.
|
||||
|
||||
For each new room you would like the bot to deliver alerts to, invite the bot to the room.
|
||||
|
||||
Then, log in as the bot using any Matrix client of your choosing, accept the room invitation from the bot's account, and log out.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#get-an-access-token).
|
||||
To enable matrix-alertmanager-receiver, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
|
||||
```yaml
|
||||
matrix_alertmanager_receiver_enabled: true
|
||||
|
||||
# Uncomment and adjust this part if you'd like to use a username different than the default
|
||||
# If you'd like to change the username for this bot, uncomment and adjust. Otherwise, remove.
|
||||
# matrix_alertmanager_receiver_config_matrix_user_id_localpart: "bot.alertmanager.receiver"
|
||||
|
||||
# Specify the bot user's access token here.
|
||||
matrix_alertmanager_receiver_config_matrix_access_token: "ACCESS_TOKEN_HERE"
|
||||
# See the "Account and room preparation" section below.
|
||||
matrix_alertmanager_receiver_config_matrix_access_token: ''
|
||||
|
||||
# Optionally, configure some mappings (URL-friendly room name -> actual Matrix room ID).
|
||||
#
|
||||
@ -82,9 +57,25 @@ See [Configuring DNS](configuring-dns.md) for details about DNS changes.
|
||||
|
||||
If you've decided to use the default hostname, you won't need to do any extra DNS configuration.
|
||||
|
||||
## Account and room preparation
|
||||
|
||||
The playbook can automatically create users, but it cannot automatically obtain access tokens, nor perform any of the other manual actions below.
|
||||
|
||||
`matrix-alertmanager-receiver` uses a bot (with a username specified in `matrix_alertmanager_receiver_config_matrix_user_id_localpart` - see above) for delivering messages. You need to **manually register this bot acccount and obtain an access token for it**.
|
||||
|
||||
1. [Register a new user](registering-users.md): `ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=bot.alertmanager.receiver password=PASSWORD_FOR_THE_BOT admin=no' --tags=register-user`
|
||||
2. [Obtain an access token](obtaining-access-tokens.md) for the bot's user account
|
||||
3. Invite the bot to a room where you'd like to alerts to be delivered
|
||||
4. Log in as the bot using any Matrix client of your choosing, accept the room invitation from the bot's account and log out
|
||||
5. (Optionally) Adjust `matrix_alertmanager_receiver_config_matrix_room_mapping` to create a mapping between the new room and its ID
|
||||
|
||||
Steps 1 and 2 above only need to be done once, while preparing your [configuration](#adjusting-the-playbook-configuration).
|
||||
|
||||
Steps 3 and 4 need to be done for each new room you'd like the bot to deliver alerts to. Step 5 is optional and provides cleaner `/alert/` URLs.
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook and potentially [adjusting your DNS records](#adjusting-dns-records), run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
Now that you've [prepared the bot account and room](#account-and-room-preparation), [configured the playbook](#adjusting-the-playbook-configuration), and potentially [adjusted your DNS records](#adjusting-dns-records), you can run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
@ -120,4 +111,6 @@ route:
|
||||
- receiver: matrix
|
||||
```
|
||||
|
||||
where `URL_HERE` looks like `https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/some-room-name` or `https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/!qporfwt:example.com`.
|
||||
.. where `URL_HERE` looks like `https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/some-room-name` or `https://matrix.example.com/matrix-alertmanager-receiver-RANDOM_VALUE_HERE/alert/!qporfwt:example.com`.
|
||||
|
||||
This bot does **not** accept room invitations automatically (like many other bots do). To deliver messages to rooms, **the bot must be joined to all rooms manually** - see Step 4 of the [Account and room preparation](#account-and-room-preparation) section.
|
||||
|
||||
@ -2,58 +2,31 @@
|
||||
|
||||
The playbook can install and configure [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) for you.
|
||||
|
||||
Hookshot can bridge [Webhooks](https://en.wikipedia.org/wiki/Webhook) from software project management services such as GitHub, GitLab, Jira, and Figma, as well as generic webhooks.
|
||||
Hookshot can bridge [Webhooks](https://en.wikipedia.org/wiki/Webhook) from software project management services such as GitHub, GitLab, JIRA, and Figma, as well as generic webhooks.
|
||||
|
||||
See the project's [documentation](https://matrix-org.github.io/matrix-hookshot/latest/hookshot.html) to learn what it does and why it might be useful to you.
|
||||
|
||||
**Note**: the playbook also supports [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), which however was deprecated by its author.
|
||||
|
||||
## Prerequisites
|
||||
## Setup Instructions
|
||||
|
||||
### Download GitHub app private key (optional)
|
||||
Refer to the [official instructions](https://matrix-org.github.io/matrix-hookshot/latest/setup.html) to learn what the individual options do.
|
||||
|
||||
If you're setting up the GitHub bridge, you need to create your GitHub app, and generate a private key file of it.
|
||||
1. Enable the bridge by adding `matrix_hookshot_enabled: true` to your `vars.yml` file
|
||||
2. For each of the services (GitHub, GitLab, Jira, Figma, generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) as required.
|
||||
3. Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab, Generic), while you must first add the required configuration and enable the others (GitHub, Jira, Figma).
|
||||
4. If you're setting up the GitHub bridge, you'll need to generate and download a private key file after you created your GitHub app. Copy the contents of that file to the variable `matrix_hookshot_github_private_key` so the playbook can install it for you, or use one of the [other methods](#manage-github-private-key-with-aux-role) explained below.
|
||||
5. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready. Hookshot can be set up individually using the tag `setup-hookshot`.
|
||||
|
||||
You need to download the private key file, if you will install the file manually or with the `aux` role. For details, see [the section below](#manage-github-private-key-with-aux-role).
|
||||
Other configuration options are available via the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables, see the comments in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) for how to use them.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
Finally, run the playbook (see [installing](installing.md)).
|
||||
|
||||
Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `GITHUB_PRIVATE_KEY_HERE` with the one created [above](#download-github-app-private-key).
|
||||
### End-to-bridge encryption
|
||||
|
||||
```yaml
|
||||
matrix_hookshot_enabled: true
|
||||
You can enable [encryption](https://matrix-org.github.io/matrix-hookshot/latest/advanced/encryption.html) for Hookshot by adding `matrix_hookshot_encryption_enabled: true` to your configuration (`vars.yml`) and [executing the playbook](installing.md) again.
|
||||
|
||||
# Uncomment to enable end-to-bridge encryption.
|
||||
# See: https://matrix-org.github.io/matrix-hookshot/latest/advanced/encryption.html
|
||||
# matrix_hookshot_experimental_encryption_enabled: true
|
||||
|
||||
# Uncomment and paste the contents of GitHub app private key to enable GitHub bridge.
|
||||
# Alternatively, you can use one of the other methods explained below on the "Manage GitHub Private Key with aux role" section.
|
||||
# matrix_hookshot_github_private_key: "GITHUB_PRIVATE_KEY_HERE"
|
||||
```
|
||||
|
||||
For each of the services (GitHub, GitLab, Jira, Figma, and generic webhooks) fill in the respective variables `matrix_hookshot_service_*` listed in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml) as required.
|
||||
|
||||
Take special note of the `matrix_hookshot_*_enabled` variables. Services that need no further configuration are enabled by default (GitLab and generic webhooks), while you must first add the required configuration and enable the others (GitHub, Jira, and Figma).
|
||||
|
||||
### Extending the configuration
|
||||
|
||||
You can configure additional options by adding the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables.
|
||||
|
||||
Refer the [official instructions](https://matrix-org.github.io/matrix-hookshot/latest/setup.html) and the comments in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml) to learn what the individual options do.
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-service hookshot` or `just setup-all`
|
||||
|
||||
`just install-service hookshot` is useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note `just setup-all` runs the `ensure-matrix-users-created` tag too.
|
||||
Should the crypto store be corrupted, you can reset it by executing this Ansible playbook with the tag `reset-hookshot-encryption` added, for example `ansible-playbook -i inventory/hosts setup.yml --tags=reset-hookshot-encryption`.
|
||||
|
||||
## Usage
|
||||
|
||||
@ -61,19 +34,11 @@ To use the bridge, you need to create a room and invite the Hookshot bot (`@hook
|
||||
|
||||
Make sure the bot is able to send state events (usually the Moderator power level in clients).
|
||||
|
||||
Send `!hookshot help` to the room to see the bridge's help menu for additional commands.
|
||||
Send a `!hookshot help` message to see a list of help commands.
|
||||
|
||||
Refer to [Hookshot's documentation](https://matrix-org.github.io/matrix-hookshot/latest/usage.html) for more details about using the bridge's various features.
|
||||
|
||||
💡 **Note**: the different listeners are bound to certain paths which might differ from those assumed by the hookshot documentation. See [URLs for bridges setup](#urls-for-bridges-setup) below.
|
||||
|
||||
### Reset crypto store
|
||||
|
||||
Should the crypto store be corrupted, you can reset it by executing this Ansible playbook with the tag `reset-hookshot-encryption` added:
|
||||
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=reset-hookshot-encryption
|
||||
```
|
||||
**Important**: Note that the different listeners are bound to certain paths which might differ from those assumed by the hookshot documentation, see [URLs for bridges setup](#urls-for-bridges-setup) below.
|
||||
|
||||
## More setup documentation
|
||||
|
||||
@ -81,31 +46,30 @@ ansible-playbook -i inventory/hosts setup.yml --tags=reset-hookshot-encryption
|
||||
|
||||
Unless indicated otherwise, the following endpoints are reachable on your `matrix.` subdomain (if the feature is enabled).
|
||||
|
||||
| Listener | Default path | Variable | Used as |
|
||||
| listener | default path | variable | used as |
|
||||
|---|---|---|---|
|
||||
| - | `/hookshot/webhooks/` | `matrix_hookshot_webhook_endpoint` | Webhook-prefix, which affects all webhook-related URLs below |
|
||||
| generic | `/hookshot/webhooks/webhook` | `matrix_hookshot_generic_endpoint` | Generic webhooks |
|
||||
| github oauth | `/hookshot/webhooks/oauth` | `matrix_hookshot_github_oauth_endpoint` | GitHub "Callback URL" |
|
||||
| jira oauth | `/hookshot/webhooks/jira/oauth` | `matrix_hookshot_jira_oauth_endpoint` | Jira OAuth |
|
||||
| jira oauth | `/hookshot/webhooks/jira/oauth` | `matrix_hookshot_jira_oauth_endpoint` | JIRA OAuth |
|
||||
| figma endpoint | `/hookshot/webhooks/figma/webhook` | `matrix_hookshot_figma_endpoint` | Figma |
|
||||
| provisioning | `/hookshot/v1/` | `matrix_hookshot_provisioning_endpoint` | Dimension [provisioning](#provisioning-api) |
|
||||
| appservice | `/hookshot/_matrix/app/` | `matrix_hookshot_appservice_endpoint` | Matrix server |
|
||||
| widgets | `/hookshot/widgetapi/` | `matrix_hookshot_widgets_endpoint` | Widgets |
|
||||
| metrics | `/metrics/hookshot` | `matrix_hookshot_metrics_enabled` and exposure enabled via `matrix_hookshot_metrics_proxying_enabled` or `matrix_metrics_exposure_enabled`. Read more in the [Metrics section](#metrics) below. | Prometheus |
|
||||
|
||||
Also see the various `matrix_hookshot_container_labels_*` variables in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml), which expose URLs publicly
|
||||
Also see the various `matrix_hookshot_container_labels_*` variables in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml), which expose URLs publicly.
|
||||
|
||||
The different listeners are also reachable *internally* in the docker-network via the container's name (configured by `matrix_hookshot_container_url`) and on different ports (e.g. `matrix_hookshot_appservice_port`). Read [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.
|
||||
The different listeners are also reachable *internally* in the docker-network via the container's name (configured by `matrix_hookshot_container_url`) and on different ports (e.g. `matrix_hookshot_appservice_port`). Read [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml) in detail for more info.
|
||||
|
||||
### Manage GitHub Private Key with aux role
|
||||
|
||||
The GitHub bridge requires you to install a private key file. This can be done in multiple ways:
|
||||
|
||||
- copy the *contents* of the downloaded file and set the variable `matrix_hookshot_github_private_key` to the contents (see example in [main.yml](../roles/custom/matrix-bridge-hookshot/defaults/main.yml)).
|
||||
- copy the *contents* of the downloaded file and set the variable `matrix_hookshot_github_private_key` to the contents (see example in [main.yml](/roles/custom/matrix-bridge-hookshot/defaults/main.yml)).
|
||||
- somehow copy the file to the path `{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}` (default: `/matrix/hookshot/private-key.pem`) on the server manually.
|
||||
- use the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux) to copy the file from an arbitrary path on your ansible client to the correct path on the server.
|
||||
|
||||
To use the `aux` role, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
|
||||
To use the `aux` role, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add the following additional configuration:
|
||||
|
||||
```yaml
|
||||
aux_file_definitions:
|
||||
|
||||
@ -84,17 +84,16 @@ Refer to the official documentation [here](https://github.com/devture/email2matr
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
To enable Email2Matrix, run the playbook with [playbook tags](playbook-tags.md) as below:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-email2matrix,start
|
||||
```
|
||||
|
||||
**Notes**:
|
||||
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just install-service email2matrix` or `just setup-all`
|
||||
- The shortcut commands with the [`just` program](just.md) are also available: `just run-tags setup-email2matrix,start` or `just setup-all`
|
||||
|
||||
`just install-service email2matrix` is useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note `just setup-all` runs the `ensure-matrix-users-created` tag too.
|
||||
`just run-tags setup-email2matrix,start` is useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note `just setup-all` runs the `ensure-matrix-users-created` tag too.
|
||||
|
||||
- After installation, you may wish to send a test email to the email address assigned to `mailbox1` (default: `mailbox1@matrix.example.com`) to make sure that Email2Matrix works as expected.
|
||||
|
||||
@ -87,16 +87,15 @@ This will instruct UVS to verify the OpenID token against any domain given in a
|
||||
|
||||
## Installing
|
||||
|
||||
After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below:
|
||||
After these variables have been set, run the playbook with [playbook tags](playbook-tags.md) as below to restart UVS:
|
||||
|
||||
<!-- NOTE: let this conservative command run (instead of install-all) to make it clear that failure of the command means something is clearly broken. -->
|
||||
```sh
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
|
||||
ansible-playbook -i inventory/hosts setup.yml --tags=setup-matrix-user-verification-service,start
|
||||
```
|
||||
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just install-service matrix-user-verification-service` or `just setup-all`
|
||||
The shortcut commands with the [`just` program](just.md) are also available: `just run-tags setup-matrix-user-verification-service,start` or `just setup-all`
|
||||
|
||||
`just install-service matrix-user-verification-service` is useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note `just setup-all` runs the `ensure-matrix-users-created` tag too.
|
||||
`just run-tags setup-matrix-user-verification-service,start` is useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note `just setup-all` runs the `ensure-matrix-users-created` tag too.
|
||||
|
||||
## Logging
|
||||
|
||||
|
||||
@ -25,7 +25,7 @@
|
||||
version: v11.4.0-0
|
||||
name: grafana
|
||||
- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-jitsi.git
|
||||
version: v9909-0
|
||||
version: v9823-1
|
||||
name: jitsi
|
||||
- src: git+https://github.com/mother-of-all-self-hosting/ansible-role-keydb.git
|
||||
version: v6.3.4-3
|
||||
|
||||
@ -6,7 +6,7 @@
|
||||
matrix_alertmanager_receiver_enabled: true
|
||||
|
||||
# renovate: datasource=docker depName=docker.io/metio/matrix-alertmanager-receiver
|
||||
matrix_alertmanager_receiver_version: 2024.12.18
|
||||
matrix_alertmanager_receiver_version: 2024.12.11
|
||||
|
||||
matrix_alertmanager_receiver_scheme: https
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
matrix_bot_mjolnir_enabled: true
|
||||
|
||||
# renovate: datasource=docker depName=matrixdotorg/mjolnir
|
||||
matrix_bot_mjolnir_version: "v1.9.1"
|
||||
matrix_bot_mjolnir_version: "v1.9.0"
|
||||
|
||||
matrix_bot_mjolnir_container_image_self_build: false
|
||||
matrix_bot_mjolnir_container_image_self_build_repo: "https://github.com/matrix-org/mjolnir.git"
|
||||
|
||||
@ -11,7 +11,7 @@ matrix_client_element_container_image_self_build_repo: "https://github.com/eleme
|
||||
matrix_client_element_container_image_self_build_low_memory_system_patch_enabled: "{{ ansible_memtotal_mb < 4096 }}"
|
||||
|
||||
# renovate: datasource=docker depName=vectorim/element-web
|
||||
matrix_client_element_version: v1.11.88
|
||||
matrix_client_element_version: v1.11.87
|
||||
|
||||
matrix_client_element_docker_image: "{{ matrix_client_element_docker_image_name_prefix }}vectorim/element-web:{{ matrix_client_element_version }}"
|
||||
matrix_client_element_docker_image_name_prefix: "{{ 'localhost/' if matrix_client_element_container_image_self_build else matrix_container_global_registry_prefix }}"
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user