ansol/matrix-docker-ansible-deploy
7
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2025-01-10 05:13:50 +00:00
Code Issues Projects Releases Wiki Activity

Update docs/configuring-playbook-mautrix-bridges.md (#3913)

Browse Source 
* Update docs/configuring-playbook-mautrix-bridges.md: edit the section "extending the configuration"

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-mautrix-bridges.md: edit section headers

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-mautrix-bridges.md: edit the section "Control the logging level"

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-mautrix-bridges.md: replace examples for service name

- Remove hangout, which has been shut down and whose role is soon to be removed from the playbook
- Add a note about the Mautrix Meta bridge

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-mautrix-bridges.md: add descriptions to each section

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-mautrix-bridges.md: move the section "Set up Double Puppeting" to "Usage"

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Rename docs/configuring-playbook-mautrix-bridges.md to docs/configuring-playbook-bridge-mautrix-bridges.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bridge-mautrix-bridges.md: edit an instruction

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bridge-mautrix-bridges.md: add the manual step for setting up Double Puppetting

Based on other documents for mautrix bridges like docs/configuring-playbook-bridge-mautrix-discord.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bridge-mautrix-bridges.md: add a note about bridges' incompatibility with Appservice Double Puppet

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bridge-mautrix-bridges.md: adopt the description on docs/configuring-playbook-appservice-double-puppet.md

Make it clear that Double Puppetting with the other methods than the appservice one has been superseded. See: https://docs.mau.fi/bridges/general/double-puppeting.html#automatically

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bridge-mautrix-bridges.md: add "recommended" label to the first method of setting up Double Puppeting

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bridge-mautrix-bridges.md: add anchor links to the official documentation

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bridge-mautrix-bridges.md: add descriptions about configuring bridge permissions

Partially based on docs/configuring-playbook-bridge-mautrix-meta-instagram.md etc.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bridge-mautrix-bridges.md: add description about the relaybot

Based on:
- the official documentation: https://docs.mau.fi/bridges/general/relay-mode.html
- docs/configuring-playbook-bridge-mautrix-whatsapp.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bridge-mautrix-bridges.md: remove a duplicated anchor link

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook.md: add an anchor link to configuring-playbook-bridge-mautrix-bridges.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bridge-mautrix-bridges.md: edit a sentence

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/configuring-playbook-bridge-mautrix-bridges.md: reflect the review

See https://github.com/spantaleev/matrix-docker-ansible-deploy/pull/3913#discussion_r1903215741

Co-authored-by: Slavi Pantaleev <slavi@devture.com>
Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

---------

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Slavi Pantaleev <slavi@devture.com>
This commit is contained in:
Suguru Hirahara 2025-01-05 03:55:51 -05:00 committed by GitHub
parent f8b779f8ed
commit 4b2e066a61
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 205 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

203
docs/configuring-playbook-bridge-mautrix-bridges.md Normal file
View File

@ -0,0 +1,203 @@
# Setting up a Generic Mautrix Bridge (optional)
The playbook can install and configure various [mautrix](https://github.com/mautrix) bridges (twitter, discord, signal, googlechat, etc.), as well as many other (non-mautrix) bridges. This is a common guide for configuring mautrix bridges.
You can see each bridge's features on the `ROADMAP.md` file in its corresponding mautrix repository.
## Adjusting the playbook configuration
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Replace SERVICENAME with one of: twitter, discord, signal, googlechat, etc.
matrix_mautrix_SERVICENAME_enabled: true
```
**Note**: for bridging to Meta's Messenger or Instagram, you would need to add `meta` with an underscore symbol (`_`) or hyphen (`-`) based on the context as prefix to each `SERVICENAME`; add `_` to variables (as in `matrix_mautrix_meta_messenger_configuration_extension_yaml` for example) and `-` to paths of the configuration files (as in `roles/custom/matrix-bridge-mautrix-meta-messenger/templates/config.yaml.j2`), respectively. **`matrix_mautrix_facebook_*` and `matrix_mautrix_instagram_*` variables belong to the deprecated components and do not control the new bridge** ([mautrix-meta](https://github.com/mautrix/meta)), which can be installed using [this playbook](configuring-playbook-bridge-mautrix-meta-messenger.md).
There are some additional things you may wish to configure about the bridge before you continue. Each bridge may have additional requirements besides `_enabled: true`. For example, the mautrix-telegram bridge (our documentation page about it is [here](configuring-playbook-bridge-mautrix-telegram.md)) requires the `matrix_mautrix_telegram_api_id` and `matrix_mautrix_telegram_api_hash` variables to be defined. Refer to each bridge's individual documentation page for details about enabling bridges.
### Configure bridge permissions (optional)
By default any user on your homeserver will be able to use the mautrix bridges. To limit who can use them you would need to configure their permissions settings.
Different levels of permission can be granted to users. For example, to **configure a user as an administrator for all bridges**, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_admin: "@alice:{{ matrix_domain }}"
```
**Alternatively** (more verbose, but allows multiple admins to be configured), you can do the same on a per-bridge basis with:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
permissions:
'@alice:{{ matrix_domain }}': admin
```
This will add the admin permission to the specific user, while keeping the default permissions.
You could also redefine the default permissions settings completely, rather than adding extra permissions. You may wish to look at `roles/custom/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` to find information on the permission settings and other options you would like to configure.
### Enable encryption (optional)
[Encryption (End-to-Bridge Encryption, E2BE) support](https://docs.mau.fi/bridges/general/end-to-bridge-encryption.html) is off by default. If you would like to enable encryption, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
**for all bridges with encryption support**:
```yaml
matrix_bridges_encryption_enabled: true
matrix_bridges_encryption_default: true
```
**Alternatively**, for a specific bridge:
```yaml
matrix_mautrix_SERVICENAME_bridge_encryption_enabled: true
matrix_mautrix_SERVICENAME_bridge_encryption_default: true
```
### Enable relay mode (optional)
[Relay mode](https://docs.mau.fi/bridges/general/relay-mode.html) is off by default. Check [the table on the official documentation](https://docs.mau.fi/bridges/general/relay-mode.html#support-table) for bridges which support relay mode.
If you would like to enable it, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
**for all bridges with relay mode support**:
```yaml
matrix_bridges_relay_enabled: true
```
**Alternatively**, for a specific bridge:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
relay:
enabled: true
```
You can only have one `matrix_mautrix_SERVICENAME_configuration_extension_yaml` definition in `vars.yml` per bridge, so if you need multiple pieces of configuration there, just merge them like this:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
permissions:
'@alice:{{ matrix_domain }}': admin
encryption:
allow: true
default: true
```
If you want to activate the relaybot in a room, send `!prefix set-relay` in the rooms where you want to use the bot (replace `!prefix` with the appropriate command prefix for the bridge, like `!signal` or `!wa`). To deactivate, send `!prefix unset-relay`.
Use `!prefix set-pl 100` to be able for the bot to modify room settings and invite others.
#### Allow anyone on the homeserver to become a relay user (optional)
By default, only admins are allowed to set themselves as relay users. To allow anyone on your homeserver to set themselves as relay users, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_mautrix_SERVICENAME_bridge_relay_admin_only: false
```
### Set the bot's username (optional)
To set the bot's username, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_mautrix_SERVICENAME_appservice_bot_username: "BOTNAME"
```
### Configure the logging level (optional)
To specify the logging level, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_mautrix_SERVICENAME_logging_level: warn
```
Replace `warn` with one of the following to control the verbosity of the logs generated: `trace`, `debug`, `info`, `warn`, `error` or `fatal`.
If you have issues with a service, and are requesting support, the higher levels of logging (those that appear earlier in the list, like `trace`) will generally be more helpful.
### Extending the configuration
There are some additional things you may wish to configure about the bridge.
Take a look at:
- `roles/custom/matrix-bridge-mautrix-SERVICENAME/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
- `roles/custom/matrix-bridge-mautrix-SERVICENAME/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_mautrix_SERVICENAME_configuration_extension_yaml` variable
## 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,ensure-matrix-users-created,start
```
**Notes**:
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) 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.
## Usage
To use the bridge, you need to start a chat with `@SERVICENAMEbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Send `login` to the bridge bot to get started. You can learn more here about authentication from the bridge's official documentation on Authentication: https://docs.mau.fi/bridges/python/SERVICENAME/authentication.html
If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
### Set up Double Puppeting (optional)
After successfully enabling bridging, you may wish to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do).
To set it up, you have 2 ways of going about it.
#### Method 1: automatically, by enabling Appservice Double Puppet (recommended)
To set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html), you could enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
Appservice Double Puppet is a homeserver appservice through which bridges (and potentially other services) can impersonate any user on the homeserver.
To enable the Appservice Double Puppet service, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_appservice_double_puppet_enabled: true
```
When enabled, double puppeting will automatically be enabled for all bridges that support double puppeting via the appservice method.
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
**Notes**:
- Previously there were multiple different automatic double puppeting methods like one with the help of the [Shared Secret Auth password provider module](./configuring-playbook-shared-secret-auth.md), but they have been superseded by this Appservice Double Puppet method. Double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future as the older methods were completely removed in the megabridge rewrites on [the upstream project](https://docs.mau.fi/bridges/general/double-puppeting.html#automatically).
<!-- TODO: remove this note if the Shared Secret Auth service has stopped working or the bridges have been removed -->
- Some bridges like [the deprecated Facebook mautrix bridge](configuring-playbook-bridge-mautrix-facebook.md) and [matrix-appservice-kakaotalk](configuring-playbook-bridge-appservice-kakaotalk.md), which is partially based on the Facebook bridge, are compatible with the Shared Secret Auth service only. These bridges automatically perform Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
#### Method 2: manually, by asking each user to provide a working access token
When using this method, **each user** that wishes to enable Double Puppeting needs to follow the following steps:
- retrieve a Matrix access token for yourself. Refer to the documentation on [how to obtain one](obtaining-access-tokens.md).
- send the access token to the bot. Example: `login-matrix MATRIX_ACCESS_TOKEN_HERE`
- make sure you don't log out the session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature
## Troubleshooting
For troubleshooting information with a specific bridge, please see the playbook documentation about it (some other document in in `docs/`) and the upstream ([mautrix](https://github.com/mautrix)) bridge documentation for that specific bridge.
Reporting bridge bugs should happen upstream, in the corresponding mautrix repository, not to us.

145
docs/configuring-playbook-mautrix-bridges.md
View File

@ -1,145 +0,0 @@
# Setting up a Generic Mautrix Bridge (optional)
The playbook can install and configure various [mautrix](https://github.com/mautrix) bridges (twitter, facebook, instagram, signal, hangouts, googlechat, etc.), as well as many other (non-mautrix) bridges. This is a common guide for configuring mautrix bridges.
You can see each bridge's features at in the `ROADMAP.md` file in its corresponding [mautrix](https://github.com/mautrix) repository.
## Adjusting the playbook configuration
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
# Replace SERVICENAME with one of: twitter, facebook, instagram, ..
matrix_mautrix_SERVICENAME_enabled: true
```
There are some additional things you may wish to configure about the bridge before you continue. Each bridge may have additional requirements besides `_enabled: true`. For example, the mautrix-telegram bridge (our documentation page about it is [here](configuring-playbook-bridge-mautrix-telegram.md)) requires the `matrix_mautrix_telegram_api_id` and `matrix_mautrix_telegram_api_hash` variables to be defined. Refer to each bridge's individual documentation page for details about enabling bridges.
To **configure a user as an administrator for all bridges**, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_admin: "@alice:{{ matrix_domain }}"
```
**Alternatively** (more verbose, but allows multiple admins to be configured), you can do the same on a per-bridge basis with:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
permissions:
'@alice:{{ matrix_domain }}': admin
```
### Encryption
Encryption support is off by default. If you would like to enable encryption, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
**for all bridges with encryption support**:
```yaml
matrix_bridges_encryption_enabled: true
matrix_bridges_encryption_default: true
```
**Alternatively**, for a specific bridge:
```yaml
matrix_mautrix_SERVICENAME_bridge_encryption_enabled: true
matrix_mautrix_SERVICENAME_bridge_encryption_default: true
```
### Relay mode
Relay mode is off by default. If you would like to enable relay mode, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
**for all bridges with relay mode support**:
```yaml
matrix_bridges_relay_enabled: true
```
**Alternatively**, for a specific bridge:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
relay:
enabled: true
```
You can only have one `matrix_mautrix_SERVICENAME_configuration_extension_yaml` definition in `vars.yml` per bridge, so if you need multiple pieces of configuration there, just merge them like this:
```yaml
matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
bridge:
permissions:
'@alice:{{ matrix_domain }}': admin
encryption:
allow: true
default: true
```
### Setting the bot's username
```yaml
matrix_mautrix_SERVICENAME_appservice_bot_username: "BOTNAME"
```
Can be used to set the username for the bridge.
### Extending the configuration
You may wish to look at `roles/custom/matrix-bridge-mautrix-SERVICENAME/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-SERVICENAME/defaults/main.yml` to find other things you would like to configure.
## 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,ensure-matrix-users-created,start
```
**Notes**:
- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account.
- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all`
`just install-all` is useful for maintaining your setup quickly ([2x-5x faster](../CHANGELOG.md#2x-5x-performance-improvements-in-playbook-runtime) than `just setup-all`) 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.
## Set up Double Puppeting
To set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) enable the [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) service for this playbook.
The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) is configured and enabled on the server for this playbook by adding
```yaml
matrix_appservice_double_puppet_enabled: true
```
This is the recommended way of setting up Double Puppeting, as it's easier to accomplish, works for all your users automatically, and has less of a chance of breaking in the future.
## Controlling the logging level
```yaml
matrix_mautrix_SERVICENAME_logging_level: WARN
```
to `vars.yml` to control the logging level, where you may replace WARN with one of the following to control the verbosity of the logs generated: TRACE, DEBUG, INFO, WARN, ERROR, or FATAL.
If you have issues with a service, and are requesting support, the higher levels of logging will generally be more helpful.
## Usage
To use the bridge, you need to start a chat with `@SERVICENAMEbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
Send `login` to the bridge bot to get started. You can learn more here about authentication from the bridge's official documentation on Authentication: https://docs.mau.fi/bridges/python/SERVICENAME/authentication.html
If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
## Troubleshooting
For troubleshooting information with a specific bridge, please see the playbook documentation about it (some other document in in `docs/`) and the upstream ([mautrix](https://github.com/mautrix)) bridge documentation for that specific bridge.
Reporting bridge bugs should happen upstream, in the corresponding mautrix repository, not to us.

2
docs/configuring-playbook.md
View File

@ -109,6 +109,8 @@ Use alternative file storage to the default `media_store` folder.
Bridges can be used to connect your Matrix installation with third-party communication networks. Bridges can be used to connect your Matrix installation with third-party communication networks.
- [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md) - a common guide for configuring mautrix bridges
- [Setting up Mautrix Discord bridging](configuring-playbook-bridge-mautrix-discord.md) - [Setting up Mautrix Discord bridging](configuring-playbook-bridge-mautrix-discord.md)
- [Setting up Mautrix Telegram bridging](configuring-playbook-bridge-mautrix-telegram.md) - [Setting up Mautrix Telegram bridging](configuring-playbook-bridge-mautrix-telegram.md)