From 73209a0554911d8266b37c15752b993b97140696 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Fri, 12 May 2023 07:00:58 +0300 Subject: [PATCH] Update aux role documentation, removing old matrix-aux references --- docs/configuring-playbook-bridge-hookshot.md | 12 ++++++------ docs/configuring-playbook-matrix-corporal.md | 2 +- docs/configuring-playbook-ssl-certificates.md | 12 ++++++------ docs/configuring-playbook-sygnal.md | 4 ++-- 4 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/configuring-playbook-bridge-hookshot.md b/docs/configuring-playbook-bridge-hookshot.md index 54f6636b9..48a66a8ea 100644 --- a/docs/configuring-playbook-bridge-hookshot.md +++ b/docs/configuring-playbook-bridge-hookshot.md @@ -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 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-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`. 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. -### 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: - 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 `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 -matrix_aux_file_definitions: +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 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 diff --git a/docs/configuring-playbook-matrix-corporal.md b/docs/configuring-playbook-matrix-corporal.md index eb635c641..2000cfd99 100644 --- a/docs/configuring-playbook-matrix-corporal.md +++ b/docs/configuring-playbook-matrix-corporal.md @@ -91,7 +91,7 @@ matrix_corporal_policy_provider_config: | } # Modify the policy below as you see fit -matrix_aux_file_definitions: +aux_file_definitions: - dest: "{{ matrix_corporal_config_dir_path }}/policy.json" content: | { diff --git a/docs/configuring-playbook-ssl-certificates.md b/docs/configuring-playbook-ssl-certificates.md index 9fa9f84b8..6a215973b 100644 --- a/docs/configuring-playbook-ssl-certificates.md +++ b/docs/configuring-playbook-ssl-certificates.md @@ -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: - 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/) -- 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 # Disable ACME / Let's Encrypt support. @@ -53,7 +53,7 @@ devture_traefik_config_certificatesResolvers_acme_enabled: false devture_traefik_ssl_dir_enabled: true # 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! devture_traefik_configuration_extension_yaml: | providers: @@ -61,9 +61,9 @@ devture_traefik_configuration_extension_yaml: | filename: /config/certificates.yml watch: true -# Use the matrix-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. -matrix_aux_file_definitions: +# Use the aux role to create our custom files on the server. +# If you'd like to do this manually, you remove this `aux_file_definitions` variable. +aux_file_definitions: # Create the privkey.pem file on the server by # uploading a file from the computer where Ansible is running. - dest: "{{ devture_traefik_ssl_dir_path }}/privkey.pem" diff --git a/docs/configuring-playbook-sygnal.md b/docs/configuring-playbook-sygnal.md index 786498c64..2fbad04c2 100644 --- a/docs/configuring-playbook-sygnal.md +++ b/docs/configuring-playbook-sygnal.md @@ -55,7 +55,7 @@ matrix_sygnal_apps: api_key: your_api_key_for_gcm # .. more configuration .. -matrix_aux_file_definitions: +aux_file_definitions: - dest: "{{ matrix_sygnal_data_path }}/my_key.p8" content: | 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 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)