matrix-docker-ansible-deploy/docs/configuring-playbook-bridge-hookshot.md

104 lines
8.5 KiB
Markdown
Raw Normal View History

2022-01-03 20:22:42 +00:00
# Setting up Hookshot (optional)
2022-03-02 19:58:11 +00:00
The playbook can install and configure [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) for you.
2022-01-03 20:22:42 +00:00
2022-02-01 12:22:03 +00:00
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.
2022-01-03 20:22:42 +00:00
See the project's [documentation](https://matrix-org.github.io/matrix-hookshot/latest/hookshot.html) to learn what it does in detail and why it might be useful to you.
2022-02-01 12:22:03 +00:00
Note: the playbook also supports [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), which however is soon to be archived by its author and to be replaced by hookshot.
2022-01-03 20:22:42 +00:00
2022-10-11 07:43:01 +00:00
2022-01-03 20:22:42 +00:00
## Setup Instructions
Refer to the [official instructions](https://matrix-org.github.io/matrix-hookshot/latest/setup.html) to learn what the individual options do.
2022-01-03 20:22:42 +00:00
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`.
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.
Finally, run the playbook (see [installing](installing.md)).
Add support for experimental encryption in Hookshot Squashed based on the work done in https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3042 commit 49932b8f3c17c4c4db7a884658c42f9a8b0550ca Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:21:31 2023 +0200 Fix syntax in matrix-bridge-hookshot/tasks/reset_encryption.yml Also, this task always does work and side-effects, so it should always report changes (`changed_when: true`). commit 6bdf7a9dcb73385313a1f34d52e27ad0cf95fb3e Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:12:41 2023 +0200 Add Hookshot validation task to ensure queue settings are set when encryption is enabled commit 8c531b7971b5dfd15ca541b5072b3eb8237cdcf9 Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:10:17 2023 +0200 Add missing variables rewiring in group_vars/matrix_servers for Hookshot commit 7d26dabc2fe692f5e1236c0e250f85996f3fd0c2 Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:08:19 2023 +0200 Add defaults for matrix_hookshot_queue_host and matrix_hookshot_queue_port commit 74f91138c92f1d1b69eb973803b882849e31a259 Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:06:17 2023 +0200 Fix syntax for connecting to additional networks for Hookshot commit ca7b41f3f2d0c2900b2805294476f70e82461304 Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:05:28 2023 +0200 Fix indentation and remove unnecessary if-statements commit ac4a918d58fc76e7332446a65609b56c5e4da00c Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:04:44 2023 +0200 Add missing --network for Hookshot This seems to have been removed by accident. commit 6a81fa208fca28951fc131cbf33b95ec78748a40 Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:02:47 2023 +0200 Make automatic Redis enabling safer, when Hookshot encryption enabled If we ever default encryption to enabled for Hookshot, we only wish to force-enable Redis if Hookshot is actually enabled. commit 75a8e0f2a6cbf1562cb99c68ad1f20e4d47735ed Author: Slavi Pantaleev <slavi@devture.com> Date: Sat Dec 16 09:01:10 2023 +0200 Fix typo commit 98ad182eaccc7ab457ead4e03cc0d4f2a525a47d Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:37:40 2023 +0100 Add defaults for Hookshot's encryption commit 29fa9fab151f513908d3e45882003da107a63c93 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:35:11 2023 +0100 Improve wording of Hookshot's encryption section commit 4f835e0560012754d7ce0b56619a97c68a297992 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:28:52 2023 +0100 use safer mount options for the container's files commit 8c93327e25c5e6af2442c676d5f264d4051c80e2 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:26:01 2023 +0100 fix filename commit 03a7bb6e7798dd95f7894311e4dd34dfa09f70fa Merge: e55d7694 06047763 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:23:44 2023 +0100 Merge branch 'HarHarLinks/hookshot-encryption' of https://github.com/real-joshua/matrix-docker-ansible-deploy into HarHarLinks/hookshot-encryption commit 06047763bbd427dde117c6635ac7301198571158 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:15:54 2023 +0100 Update roles/custom/matrix-bridge-hookshot/templates/config.yml.j2 change the if statement to not require a variable with a length > 0 and add a filter to json for the redis host Co-authored-by: Slavi Pantaleev <slavi@devture.com> commit e55d769465bd299081464e68d34851729d42d5ff Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:13:50 2023 +0100 clarify that Redis is required, standardadise on Hookshot with an upper-case first letter for consistency commit 66706e4535704deba63e5aa2102f324f9b14dae3 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 22:08:20 2023 +0100 Update roles/custom/matrix-bridge-hookshot/templates/config.yml.j2 fix for a typo Co-authored-by: Slavi Pantaleev <slavi@devture.com> commit f6aaeb9a16f84409d31188e696885afed89fbdcc Merge: e5d34002 869dd33f Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 00:22:34 2023 +0100 Merge branch 'master' into HarHarLinks/hookshot-encryption commit e5d34002fd6c39c3e18df04e20d0c8b25475db78 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Fri Dec 15 00:09:27 2023 +0100 Add Jinja loop to allow adding multiple networks commit 69f947782d6e072c3edc4ee4c7d5ccf69eccf3fd Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Thu Dec 14 23:52:41 2023 +0100 split if statements for the message queue and experimental encryption support into seperate statements commit 4c13be1c89ffb1b06475c7da546f7956e67b36a1 Author: Joshua Hoffmann <joshua.hoffmann@b1-systems.de> Date: Thu Dec 14 23:31:19 2023 +0100 change variable name per spantaleev's suggestion (https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/2979#discussion_r1379015551) commit 9905309aa9448f91297f8c7618bf62682eee2af7 Author: HarHarLinks <kim.brose@rwth-aachen.de> Date: Wed Nov 1 16:14:04 2023 +0100 amend docs commit 94abf2d5bde63919c6b5597f3142eea5fed73815 Author: HarHarLinks <kim.brose@rwth-aachen.de> Date: Wed Nov 1 16:05:22 2023 +0100 draft encryption support for hookshot
2023-12-16 07:23:35 +00:00
### End-to-bridge encryption
You can enable [experimental encryption](https://matrix-org.github.io/matrix-hookshot/latest/advanced/encryption.html) for Hookshot by adding `matrix_hookshot_experimental_encryption_enabled: true` to your configuration (`vars.yml`) and [executing the playbook](installing.md) again.
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 -K --tags=reset-hookshot-encryption`).
2022-10-11 07:43:01 +00:00
## Usage
Create a room and invite the Hookshot bot (`@hookshot:DOMAIN`) to it.
Make sure the bot is able to send state events (usually the Moderator power level in clients).
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 brige's various features.
**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
### URLs for bridges setup
Unless indicated otherwise, the following endpoints are reachable on your `matrix.` subdomain (if the feature is enabled).
| listener | default path | variable | used as |
|---|---|---|---|
| webhooks | `/hookshot/webhooks/` | `matrix_hookshot_webhook_endpoint` | generics, GitHub "Webhook URL", GitLab "URL", etc. |
| 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 |
| 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 in [default/main.yml](/roles/custom/matrix-bridge-hookshot/default/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.
### 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)).
- 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 additional configuration:
```yaml
aux_file_definitions:
- dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}"
content: "{{ lookup('file', '/path/to/your-github-private-key.pem') }}"
mode: '0400'
owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_groupname }}"
```
For more information, see the documentation in the [default configuration of the aux role](https://github.com/mother-of-all-self-hosting/ansible-role-aux/blob/main/defaults/main.yml).
### Provisioning API
2022-01-03 20:22:42 +00:00
2022-01-10 23:19:29 +00:00
The provisioning API will be enabled automatically if you set `matrix_dimension_enabled: true` and provided a `matrix_hookshot_provisioning_secret`, unless you override it either way. To use hookshot with dimension, you will need to enter as "Provisioning URL": `http://matrix-hookshot:9002`, which is made up of the variables `matrix_hookshot_container_url` and `matrix_hookshot_provisioning_port`.
### Metrics
2022-01-10 23:19:29 +00:00
Metrics are **only enabled by default** if the builtin [Prometheus](configuring-playbook-prometheus-grafana.md) is enabled (by default, Prometheus isn't enabled). If so, metrics will automatically be collected by Prometheus and made available in Grafana. You will, however, need to set up your own Dashboard for displaying them.
To explicitly enable metrics, use `matrix_hookshot_metrics_enabled: true`. This only exposes metrics over the container network, however.
**To collect metrics from an external Prometheus server**, besides enabling metrics as described above, you will also need to enable metrics exposure on `https://matrix.DOMAIN/metrics/hookshot` by:
- either enabling metrics exposure for Hookshot via `matrix_hookshot_metrics_proxying_enabled: true`
- or enabling metrics exposure for all services via `matrix_metrics_exposure_enabled: true`
Whichever one you go with, by default metrics are exposed publicly **without** password-protection. See [the Prometheus and Grafana docs](configuring-playbook-prometheus-grafana.md) for details about password-protection for metrics.
### Collision with matrix-appservice-webhooks
If you are also running [matrix-appservice-webhooks](configuring-playbook-bridge-appservice-webhooks.md), it reserves its namespace by the default setting `matrix_appservice_webhooks_user_prefix: '_webhook_'`. You should take care if you modify its or hookshot's prefix that they do not collide with each other's namespace (default `matrix_hookshot_generic_userIdPrefix: '_webhooks_'`).