mirror of
https://github.com/spantaleev/matrix-docker-ansible-deploy.git
synced 2024-12-10 15:20:34 +00:00
Update aux role documentation, removing old matrix-aux references
This commit is contained in:
parent
f2825382f9
commit
73209a0554
@ -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
|
||||
|
||||
|
@ -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: |
|
||||
{
|
||||
|
@ -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"
|
||||
|
@ -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)
|
||||
|
||||
|
Loading…
Reference in New Issue
Block a user