spantaleev/matrix-docker-ansible-deploy
1
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2026-07-17 19:01:04 +10:00
Code Issues Packages Projects Releases Wiki Activity

Rename matrix_hookshot_* variables to matrix_bridge_hookshot_*

Browse Source 
Part of adopting a uniform naming policy for bridge variables,
where the variable prefix matches the role directory name.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Slavi Pantaleev
2026-07-16 14:48:51 +03:00
parent 6e4992a2fe
commit 7ccc9c515e
12 changed files with 507 additions and 507 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/configuring-playbook-bridge-hookshot.md
+25 -25
View File
@@ -29,15 +29,15 @@ You need to download the private key file, if you will install the file manually
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).
```yaml
matrix_hookshot_enabled: true
matrix_bridge_hookshot_enabled: true
# Uncomment to enable end-to-bridge encryption.
# See: https://matrix-org.github.io/matrix-hookshot/latest/advanced/encryption.html
# matrix_hookshot_encryption_enabled: true
# matrix_bridge_hookshot_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"
# matrix_bridge_hookshot_github_private_key: "GITHUB_PRIVATE_KEY_HERE"
```
> [!NOTE]
@@ -50,9 +50,9 @@ matrix_hookshot_enabled: true
>
> These are experimental homeserver-wide features (as is Hookshot's encryption support itself), so enable them deliberately.
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.
For each of the services (GitHub, GitLab, Jira, Figma, and generic webhooks) fill in the respective variables `matrix_bridge_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).
Take special note of the `matrix_bridge_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
@@ -61,7 +61,7 @@ There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-hookshot/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-hookshot/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_hookshot_configuration_extension_yaml` and `matrix_hookshot_registration_extension_yaml` variables
- `roles/custom/matrix-bridge-hookshot/templates/config.yaml.j2` for the bridge's default configuration. You can override settings (even those that don't have dedicated playbook variables) using the `matrix_bridge_hookshot_configuration_extension_yaml` and `matrix_bridge_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.
@@ -106,31 +106,31 @@ Unless indicated otherwise, the following endpoints are reachable on your `matri
| 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 |
| figma endpoint | `/hookshot/webhooks/figma/webhook` | `matrix_hookshot_figma_endpoint` | Figma |
| appservice | `/hookshot/_matrix/app/` | `matrix_hookshot_appservice_endpoint` | Matrix server |
| widgets | `/hookshot/widgetapi/` | `matrix_hookshot_widgets_endpoint` | Widgets |
| - | `/hookshot/webhooks/` | `matrix_bridge_hookshot_webhook_endpoint` | Webhook-prefix, which affects all webhook-related URLs below |
| generic | `/hookshot/webhooks/webhook` | `matrix_bridge_hookshot_generic_endpoint` | Generic webhooks |
| github oauth | `/hookshot/webhooks/oauth` | `matrix_bridge_hookshot_github_oauth_endpoint` | GitHub "Callback URL" |
| jira oauth | `/hookshot/webhooks/jira/oauth` | `matrix_bridge_hookshot_jira_oauth_endpoint` | Jira OAuth |
| figma endpoint | `/hookshot/webhooks/figma/webhook` | `matrix_bridge_hookshot_figma_endpoint` | Figma |
| appservice | `/hookshot/_matrix/app/` | `matrix_bridge_hookshot_appservice_endpoint` | Matrix server |
| widgets | `/hookshot/widgetapi/` | `matrix_bridge_hookshot_widgets_endpoint` | Widgets |
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_bridge_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_bridge_hookshot_container_url`) and on different ports (e.g. `matrix_bridge_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.
- copy the *contents* of the downloaded file and set the variable `matrix_bridge_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_bridge_hookshot_base_path }}/{{ matrix_bridge_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 `vars.yml` file:
To use the `aux` role, make sure the `matrix_bridge_hookshot_github_private_key` variable is empty. Then add the following configuration to your `vars.yml` file:
```yaml
aux_file_definitions:
- dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}"
- dest: "{{ matrix_bridge_hookshot_base_path }}/{{ matrix_bridge_hookshot_github_private_key_file }}"
content: "{{ lookup('file', '/path/to/your-github-private-key.pem') }}"
mode: '0400'
owner: "{{ matrix_user_name }}"
@@ -149,23 +149,23 @@ To enable the metrics, add the following configuration to your `vars.yml` file:
```yaml
# Expose metrics (locally, on the container network).
matrix_hookshot_metrics_enabled: true
matrix_bridge_hookshot_metrics_enabled: true
```
**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.example.com/metrics/hookshot` by adding the following configuration to your `vars.yml` file:
```yaml
matrix_hookshot_metrics_proxying_enabled: true
matrix_bridge_hookshot_metrics_proxying_enabled: true
```
By default metrics are exposed publicly **without** password-protection. To password-protect the metrics with dedicated credentials, add the following configuration to your `vars.yml` file:
```yaml
matrix_hookshot_container_labels_metrics_middleware_basic_auth_enabled: true
matrix_hookshot_container_labels_metrics_middleware_basic_auth_users: ''
matrix_bridge_hookshot_container_labels_metrics_middleware_basic_auth_enabled: true
matrix_bridge_hookshot_container_labels_metrics_middleware_basic_auth_users: ''
```
To `matrix_hookshot_container_labels_metrics_middleware_basic_auth_users`, set the Basic Authentication credentials (raw `htpasswd` file content) used to protect the endpoint. See https://doc.traefik.io/traefik/middlewares/http/basicauth/#users for details about it.
To `matrix_bridge_hookshot_container_labels_metrics_middleware_basic_auth_users`, set the Basic Authentication credentials (raw `htpasswd` file content) used to protect the endpoint. See https://doc.traefik.io/traefik/middlewares/http/basicauth/#users for details about it.
**Note**: alternatively, you can use `matrix_metrics_exposure_enabled` to expose all services on this `/metrics/*` feature, and you can use `matrix_metrics_exposure_http_basic_auth_enabled` and `matrix_metrics_exposure_http_basic_auth_users` to password-protect the metrics of them. See [this section](configuring-playbook-prometheus-grafana.md#collecting-metrics-to-an-external-prometheus-server) for more information.
@@ -185,5 +185,5 @@ The default logging level for this component is `warn`. If you want to increase
```yaml
# Valid values: error, warn, info, debug
matrix_hookshot_logging_level: debug
matrix_bridge_hookshot_logging_level: debug
```