Update aux role documentation, removing old matrix-aux references

This commit is contained in:
Slavi Pantaleev 2023-05-12 07:00:58 +03:00
parent f2825382f9
commit 73209a0554
4 changed files with 15 additions and 15 deletions

View File

@ -16,7 +16,7 @@ Refer to the [official instructions](https://matrix-org.github.io/matrix-hooksho
1. Enable the bridge by adding `matrix_hookshot_enabled: true` to your `vars.yml` file 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. 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). 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-matrix-aux-role) explained below. 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`. 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. 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.
@ -58,23 +58,23 @@ See also `matrix_hookshot_matrix_nginx_proxy_configuration` in [init.yml](/roles
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 matrix-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 `matrix-aux` role 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 `matrix-aux`, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add to `matrix-aux` configuration like this: To use the `aux` role, make sure the `matrix_hookshot_github_private_key` variable is empty. Then add the following additional configuration:
```yaml ```yaml
matrix_aux_file_definitions: aux_file_definitions:
- dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}" - dest: "{{ matrix_hookshot_base_path }}/{{ matrix_hookshot_github_private_key_file }}"
content: "{{ lookup('file', '/path/to/your-github-private-key.pem') }}" content: "{{ lookup('file', '/path/to/your-github-private-key.pem') }}"
mode: '0400' mode: '0400'
owner: "{{ matrix_user_username }}" owner: "{{ matrix_user_username }}"
group: "{{ matrix_user_groupname }}" group: "{{ matrix_user_groupname }}"
``` ```
For more info see the documentation in the [matrix-aux base configuration file](/roles/custom/matrix-aux/defaults/main.yml). 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 ### Provisioning API

View File

@ -91,7 +91,7 @@ matrix_corporal_policy_provider_config: |
} }
# Modify the policy below as you see fit # Modify the policy below as you see fit
matrix_aux_file_definitions: aux_file_definitions:
- dest: "{{ matrix_corporal_config_dir_path }}/policy.json" - dest: "{{ matrix_corporal_config_dir_path }}/policy.json"
content: | content: |
{ {

View File

@ -40,9 +40,9 @@ If you'd like to use your own SSL certificates, instead of the default (SSL cert
To use your own SSL certificates with Traefik, you need to: To use your own SSL certificates with Traefik, you need to:
- disable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) / [Let's Encrypt](https://letsencrypt.org/) support - disable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) / [Let's Encrypt](https://letsencrypt.org/) support
- put a custom Traefik configuration file on the server, with the help of this Ansible playbook (via the `matrix-aux` role) or manually - put a custom Traefik configuration file on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually
- register your custom configuration file with Traefik, by adding an extra provider of type [file](https://doc.traefik.io/traefik/providers/file/) - register your custom configuration file with Traefik, by adding an extra provider of type [file](https://doc.traefik.io/traefik/providers/file/)
- put the SSL files on the server, with the help of this Ansible playbook (via the `matrix-aux` role) or manually - put the SSL files on the server, with the help of this Ansible playbook (via the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux)) or manually
```yaml ```yaml
# Disable ACME / Let's Encrypt support. # Disable ACME / Let's Encrypt support.
@ -53,7 +53,7 @@ devture_traefik_config_certificatesResolvers_acme_enabled: false
devture_traefik_ssl_dir_enabled: true devture_traefik_ssl_dir_enabled: true
# Tell Traefik to load our custom configuration file (certificates.yml). # Tell Traefik to load our custom configuration file (certificates.yml).
# The file is created below, in `matrix_aux_file_definitions`. # The file is created below, in `aux_file_definitions`.
# The `/config/..` path is an in-container path, not a path on the host (like `/matrix/traefik/config`). Do not change it! # The `/config/..` path is an in-container path, not a path on the host (like `/matrix/traefik/config`). Do not change it!
devture_traefik_configuration_extension_yaml: | devture_traefik_configuration_extension_yaml: |
providers: providers:
@ -61,9 +61,9 @@ devture_traefik_configuration_extension_yaml: |
filename: /config/certificates.yml filename: /config/certificates.yml
watch: true watch: true
# Use the matrix-aux role to create our custom files on the server. # Use the aux role to create our custom files on the server.
# If you'd like to do this manually, you remove this `matrix_aux_file_definitions` variable. # If you'd like to do this manually, you remove this `aux_file_definitions` variable.
matrix_aux_file_definitions: aux_file_definitions:
# Create the privkey.pem file on the server by # Create the privkey.pem file on the server by
# uploading a file from the computer where Ansible is running. # uploading a file from the computer where Ansible is running.
- dest: "{{ devture_traefik_ssl_dir_path }}/privkey.pem" - dest: "{{ devture_traefik_ssl_dir_path }}/privkey.pem"

View File

@ -55,7 +55,7 @@ matrix_sygnal_apps:
api_key: your_api_key_for_gcm api_key: your_api_key_for_gcm
# .. more configuration .. # .. more configuration ..
matrix_aux_file_definitions: aux_file_definitions:
- dest: "{{ matrix_sygnal_data_path }}/my_key.p8" - dest: "{{ matrix_sygnal_data_path }}/my_key.p8"
content: | content: |
some some
@ -73,7 +73,7 @@ Configuring [GCM/FCM](https://firebase.google.com/docs/cloud-messaging/) is easi
To configure [APNS](https://developer.apple.com/notifications/) (Apple Push Notification Service), you'd need to provide one or more certificate files. To configure [APNS](https://developer.apple.com/notifications/) (Apple Push Notification Service), you'd need to provide one or more certificate files.
To do that, the above example configuration: To do that, the above example configuration:
- makes use of the `matrix-aux` role (and its `matrix_aux_file_definitions` variable) to make the playbook install files into `/matrix/sygnal/data` (the `matrix_sygnal_data_path` variable). See `roles/custom/matrix-aux/defaults/main.yml` for usage examples. It also makes sure the files are owned by `matrix:matrix`, so that Sygnal can read them. Of course, you can also install these files manually yourself, if you'd rather not use `matrix-aux`. - makes use of the [`aux` role](https://github.com/mother-of-all-self-hosting/ansible-role-aux) (and its `aux_file_definitions` variable) to make the playbook install files into `/matrix/sygnal/data` (the `matrix_sygnal_data_path` variable). See [`defaults/main.yml` file](https://github.com/mother-of-all-self-hosting/ansible-role-aux/blob/main/defaults/main.yml) of the `aux` role for usage examples. It also makes sure the files are owned by `matrix:matrix`, so that Sygnal can read them. Of course, you can also install these files manually yourself, if you'd rather not use `aux`.
- references these files in the Sygnal configuration (`matrix_sygnal_apps`) using a path like `/data/..` (the `/matrix/sygnal/data` directory on the host system is mounted into the `/data` directory inside the container) - references these files in the Sygnal configuration (`matrix_sygnal_apps`) using a path like `/data/..` (the `/matrix/sygnal/data` directory on the host system is mounted into the `/data` directory inside the container)