mirror/matrix-docker-ansible-deploy
1
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2025-02-12 01:58:58 +01:00
Code Issues Packages Projects Releases Wiki Activity

Compare commits

base: mirror:d23be036000de5bd2462dcaca1157c3a463b178e
Branches Tags
mirror:master
mirror:renovate/zeratax-matrix-registration-0.x
mirror:synapse-cache-tuning
mirror:HarHarLinks/hookshot-encryption
..
compare: mirror:56e9343f2b7a857965981d9ac738b8adfa485137
Branches Tags
mirror:master
mirror:renovate/zeratax-matrix-registration-0.x
mirror:synapse-cache-tuning
mirror:HarHarLinks/hookshot-encryption

1 Commits
d23be03600 ... 56e9343f2b

Author SHA1 Message Date
Suguru Hirahara
56e9343f2b
Merge a2445af6d0100a43d6011b31402b9ae8f0c38f0c into 8e41eb57c50cd642a33715c993ca2cf132009a5f 2024-12-17 21:14:36 +02:00
5 changed files with 31 additions and 69 deletions
Show Stats Expand all files Collapse all files

78
docs/configuring-playbook-bridge-hookshot.md
View File

@ -8,58 +8,31 @@ SPDX-License-Identifier: AGPL-3.0-or-later
The playbook can install and configure [matrix-hookshot](https://github.com/matrix-org/matrix-hookshot) for you. 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. 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. **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 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.
matrix_hookshot_enabled: true
# Uncomment to enable end-to-bridge encryption. 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`.
# 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.
## Usage ## Usage
@ -67,19 +40,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). 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. 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. **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.
### 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
```
## More setup documentation ## More setup documentation
@ -87,31 +52,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). 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 | | - | `/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 | | generic | `/hookshot/webhooks/webhook` | `matrix_hookshot_generic_endpoint` | Generic webhooks |
| github oauth | `/hookshot/webhooks/oauth` | `matrix_hookshot_github_oauth_endpoint` | GitHub "Callback URL" | | 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 | | figma endpoint | `/hookshot/webhooks/figma/webhook` | `matrix_hookshot_figma_endpoint` | Figma |
| provisioning | `/hookshot/v1/` | `matrix_hookshot_provisioning_endpoint` | Dimension [provisioning](#provisioning-api) | | provisioning | `/hookshot/v1/` | `matrix_hookshot_provisioning_endpoint` | Dimension [provisioning](#provisioning-api) |
| appservice | `/hookshot/_matrix/app/` | `matrix_hookshot_appservice_endpoint` | Matrix server | | appservice | `/hookshot/_matrix/app/` | `matrix_hookshot_appservice_endpoint` | Matrix server |
| widgets | `/hookshot/widgetapi/` | `matrix_hookshot_widgets_endpoint` | Widgets | | 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 | | 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 ### 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: 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. - 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. - 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 ```yaml
aux_file_definitions: aux_file_definitions:

9
docs/configuring-playbook-email2matrix.md
View File

@ -90,17 +90,16 @@ Refer to the official documentation [here](https://github.com/devture/email2matr
## Installing ## 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 ```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start ansible-playbook -i inventory/hosts setup.yml --tags=setup-email2matrix,start
``` ```
**Notes**: **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. - 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.

9
docs/configuring-playbook-user-verification-service.md
View File

@ -93,16 +93,15 @@ This will instruct UVS to verify the OpenID token against any domain given in a
## Installing ## 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 ```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 ## Logging

2
roles/custom/matrix-alertmanager-receiver/defaults/main.yml
View File

@ -10,7 +10,7 @@
matrix_alertmanager_receiver_enabled: true matrix_alertmanager_receiver_enabled: true
# renovate: datasource=docker depName=docker.io/metio/matrix-alertmanager-receiver # 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 matrix_alertmanager_receiver_scheme: https

2
roles/custom/matrix-bot-mjolnir/defaults/main.yml
View File

@ -9,7 +9,7 @@
matrix_bot_mjolnir_enabled: true matrix_bot_mjolnir_enabled: true
# renovate: datasource=docker depName=matrixdotorg/mjolnir # 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: false
matrix_bot_mjolnir_container_image_self_build_repo: "https://github.com/matrix-org/mjolnir.git" matrix_bot_mjolnir_container_image_self_build_repo: "https://github.com/matrix-org/mjolnir.git"