Use common descriptions for mautrix bridges to improve consistency (#…

…3914) * Update docs for mautrix bridges: common section for extending the configuration Add links to the common guide for configuring mautrix bridges Signed-off-by: Suguru Hirahara <[email protected]> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: add the sections 'extending the configuration' Signed-off-by: Suguru Hirahara <[email protected]> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: add the common section "extending the configuration" based on docs for mautrix bridges Signed-off-by: Suguru Hirahara <[email protected]> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: edit the top section Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for mautrix bridges: common section for setting up Double Puppeting Based on docs/configuring-playbook-bridge-mautrix-meta-instagram.md Signed-off-by: Suguru Hirahara <[email protected]> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: common section for setting up Double Puppetting Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for mautrix bridges: replace duplicated descriptions for setting up Double Puppeting with a link to docs/configuring-playbook-bridge-mautrix-bridges.md Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for mautrix bridges: remove the section for setting up Double Puppeting The instruction has been described already in the section for prerequisites Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for mautrix bridges: add sections for enabling double puppeting Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for mautrix bridges: adopt common descriptions about bridge permissions Signed-off-by: Suguru Hirahara <[email protected]> * Update docs/configuring-playbook-bridge-mautrix-whatsapp.md: remove description for relay-bot For WhatsApp the default relay mode is used and the description for it is available on the common guide for configuring mautrix bridges. Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for mautrix bridges: remove descriptions about permissions in favor of the common one on docs/configuring-playbook-bridge-mautrix-bridges.md Signed-off-by: Suguru Hirahara <[email protected]> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: remove a redundant instruction for referring to the section for troubleshooting The section is just below the instruction. Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for mautrix bridges: add notes about double puppeting with the Shared Secret Auth Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for mautrix bridges: remove redundant descriptions Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for mautrix bridges: remove links to the description about the relay mode from configuring-playbook-bridge-mautrix-bridges.md Signed-off-by: Suguru Hirahara <[email protected]> * Update docs/configuring-playbook-bridge-mautrix-telegram.md: move the section for instruction about using the bridge for direct chat only Signed-off-by: Suguru Hirahara <[email protected]> * Update docs/configuring-playbook-bridge-mautrix-bridges.md: add configuration for relay to an example of matrix_mautrix_SERVICENAME_configuration_extension_yaml Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for mautrix bridges: add a header for the reference to the common guide Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for mautrix bridges: adopt the common description for the section "Usage" Fix docs/configuring-playbook-bridge-mautrix-bridges.md: simplify the instruction to refer each documentation page (note that there are two formats of the links: https://docs.mau.fi/bridges/python/SERVICENAME/authentication.html and https://docs.mau.fi/bridges/go/SERVICENAME/authentication.html) Signed-off-by: Suguru Hirahara <[email protected]> * Update docs for mautrix bridges: edit anchor links to official documentation pages - Add links to the official documentation pages - Remove links to Hangouts' documentation page: the links have been replaced with ones to Google Chat bridge and the resources about Hangouts bridge have been removed - Replace links to documentation pages in python version with ones in go version Signed-off-by: Suguru Hirahara <[email protected]> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: add a note about variable names Signed-off-by: Suguru Hirahara <[email protected]> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: re-add the section for instruction about appservice double puppeting Signed-off-by: Suguru Hirahara <[email protected]> --------- Signed-off-by: Suguru Hirahara <[email protected]> Co-authored-by: Suguru Hirahara <[email protected]>
spantaleev · Jan 9, 2025 · 5cf99af · 5cf99af
1 parent 5f60223
commit 5cf99af
Show file tree

Hide file tree

Showing 18 changed files with 199 additions and 538 deletions.
diff --git a/docs/configuring-playbook-bridge-appservice-kakaotalk.md b/docs/configuring-playbook-bridge-appservice-kakaotalk.md
@@ -8,9 +8,13 @@ See the project's [documentation](https://src.miscworks.net/fair/matrix-appservi
 
 ## Prerequisite (optional)
 
+### Enable Shared Secret Auth
+
 If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) for this playbook.
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
 
 ## Adjusting the playbook configuration
 
@@ -20,9 +24,7 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_appservice_kakaotalk_enabled: true
 ```
 
-You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
-
-### Additional configuration
+### Extending the configuration
 
 There are some additional things you may wish to configure about the bridge.
 
@@ -52,26 +54,4 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 To use the bridge, you need to start a chat with `@kakaotalkbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-Send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password.
-
-### 💡 Set up Double Puppeting
-
-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 Shared Secret Auth
-
-The bridge automatically performs Double Puppeting if [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
-
-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.
-
-#### 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 `Appservice-Kakaotalk` device some time in the future, as that would break the Double Puppeting feature
+You then need to send `login --save EMAIL_OR_PHONE_NUMBER` to the bridge bot to enable bridging for your Kakaotalk account. The `--save` flag may be omitted, if you'd rather not save your password.
diff --git a/docs/configuring-playbook-bridge-appservice-webhooks.md b/docs/configuring-playbook-bridge-appservice-webhooks.md
@@ -48,7 +48,7 @@ To use the bridge, you need to invite the bridge bot user to your room in either
 - Send `/invite @_webhook:example.com` (**Note**: Make sure you have administration permissions in your room)
 - Add the bridge bot to a private channel (personal channels imply you being an administrator)
 
-You then need to send a message to the bridge bot in order to receive a private message including the webhook link:
+You then need to send a message to the bridge bot to receive a private message including the webhook link:
 
 ```
 !webhook

diff --git a/docs/configuring-playbook-bridge-beeper-linkedin.md b/docs/configuring-playbook-bridge-beeper-linkedin.md
@@ -1,9 +1,19 @@
 # Setting up Beeper Linkedin bridging (optional)
 
-The playbook can install and configure [beeper-linkedin](https://github.com/beeper/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) Messaging. This bridge is based on the mautrix-python framework and can be configured in a similar way to the other mautrix bridges
+The playbook can install and configure [beeper-linkedin](https://github.com/beeper/linkedin) for you, for bridging to [LinkedIn](https://www.linkedin.com/) Messaging. This bridge is based on the mautrix-python framework and can be configured in a similar way to the mautrix bridges.
 
 See the project's [documentation](https://github.com/beeper/linkedin/blob/master/README.md) to learn what it does and why it might be useful to you.
 
+## Prerequisite
+
+### Enable Appservice Double Puppet or Shared Secret Auth (optional)
+
+If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
+
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
+
 ## Adjusting the playbook configuration
 
 To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
@@ -12,25 +22,13 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_beeper_linkedin_enabled: true
 ```
 
-There are some additional things you may wish to configure about the bridge before you continue.
+### Extending the configuration
 
-Encryption support is off by default. If you would like to enable encryption, add the following to your `vars.yml` file:
+There are some additional things you may wish to configure about the bridge.
 
-```yaml
-matrix_beeper_linkedin_bridge_encryption_allow: true
-matrix_beeper_linkedin_bridge_encryption_default: true
-```
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [relay mode](configuring-playbook-bridge-mautrix-bridges.md#enable-relay-mode-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc.
 
-If you would like to be able to administrate the bridge from your account it can be configured like this:
-
-```yaml
-matrix_beeper_linkedin_configuration_extension_yaml: |
-  bridge:
-    permissions:
-      '@alice:{{ matrix_domain }}': admin
-```
-
-You may wish to look at `roles/custom/matrix-bridge-beeper-linkedin/templates/config.yaml.j2` to find other things you would like to configure.
+**Note**: when following the guide to configure the bridge, make sure to replace `_mautrix_SERVICENAME_` in the variable names with `_beeper_linkedin_`.
 
 ## Installing
 
@@ -49,23 +47,11 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
   `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 by enabling Appservice Double Puppet or Shared Secret Auth
-
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
-
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) 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.
-
-Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
-
 ## Usage
 
 To use the bridge, you need to start a chat with `@linkedinbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
 
-Send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to enable bridging for your LinkedIn account.
-
-If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
-
-After successfully enabling bridging, you may wish to [set up Double Puppeting](#set-up-double-puppeting-by-enabling-appservice-double-puppet-or-shared-secret-auth), if you haven't already done so.
+You then need to send `login YOUR_LINKEDIN_EMAIL_ADDRESS` to the bridge bot to enable bridging for your LinkedIn account.
 
 ## Troubleshooting
 

diff --git a/docs/configuring-playbook-bridge-mautrix-bridges.md b/docs/configuring-playbook-bridge-mautrix-bridges.md
@@ -27,6 +27,8 @@ Different levels of permission can be granted to users. For example, to **config
 matrix_admin: "@alice:{{ matrix_domain }}"
 ```
 
+If you don't define the `matrix_admin` in your configuration (e.g. `matrix_admin: @alice:example.com`), then there's no admin by default.
+
 **Alternatively** (more verbose, but allows multiple admins to be configured), you can do the same on a per-bridge basis with:
 
 ```yaml
@@ -84,6 +86,8 @@ You can only have one `matrix_mautrix_SERVICENAME_configuration_extension_yaml`
 ```yaml
 matrix_mautrix_SERVICENAME_configuration_extension_yaml: |
   bridge:
+    relay:
+      enabled: true
     permissions:
       '@alice:{{ matrix_domain }}': admin
     encryption:
@@ -153,7 +157,7 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 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
+For details about the next steps, refer to each bridge's individual documentation page.
 
 If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
 

diff --git a/docs/configuring-playbook-bridge-mautrix-discord.md b/docs/configuring-playbook-bridge-mautrix-discord.md
@@ -1,5 +1,7 @@
 # Setting up Mautrix Discord bridging (optional)
 
+<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
+
 **Note**: bridging to [Discord](https://discordapp.com/) can also happen via the [mx-puppet-discord](configuring-playbook-bridge-mx-puppet-discord.md) and [matrix-appservice-discord](configuring-playbook-bridge-appservice-discord.md) bridges supported by the playbook.
 - For using as a Bot we recommend the [Appservice Discord](configuring-playbook-bridge-appservice-discord.md), because it supports plumbing.
 - For personal use with a discord account we recommend the `mautrix-discord` bridge (the one being discussed here), because it is the most fully-featured and stable of the 3 Discord bridges supported by the playbook.
@@ -18,7 +20,9 @@ If this is a dealbreaker for you, consider using one of the other Discord bridge
 
 If you want to set up [Double Puppeting](https://docs.mau.fi/bridges/general/double-puppeting.html) (hint: you most likely do) for this bridge automatically, you need to have enabled [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service for this playbook.
 
-For details about configuring Double Puppeting for this bridge, see the section below: [Set up Double Puppeting](#-set-up-double-puppeting)
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#set-up-double-puppeting-optional) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about setting up Double Puppeting.
+
+**Note**: double puppeting with the Shared Secret Auth works at the time of writing, but is deprecated and will stop working in the future.
 
 ## Adjusting the playbook configuration
 
@@ -28,16 +32,12 @@ To enable the bridge, add the following configuration to your `inventory/host_va
 matrix_mautrix_discord_enabled: true
 ```
 
-You may optionally wish to add some [Additional configuration](#additional-configuration), or to [prepare for double-puppeting](#set-up-double-puppeting) before the initial installation.
-
-### Additional configuration
+### 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-discord/defaults/main.yml` for some variables that you can customize via your `vars.yml` file
-- `roles/custom/matrix-bridge-mautrix-discord/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_discord_configuration_extension_yaml` variable
+<!-- NOTE: common relay mode is not supported for this bridge -->
+See [this section](configuring-playbook-bridge-mautrix-bridges.md#extending-the-configuration) on the [common guide for configuring mautrix bridges](configuring-playbook-bridge-mautrix-bridges.md) for details about variables that you can customize and the bridge's default configuration, including [bridge permissions](configuring-playbook-bridge-mautrix-bridges.md#configure-bridge-permissions-optional), [encryption support](configuring-playbook-bridge-mautrix-bridges.md#enable-encryption-optional), [bot's username](configuring-playbook-bridge-mautrix-bridges.md#setting-the-bot-s-username-optional), etc.
 
 ## Installing
 
@@ -60,6 +60,8 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
 
 ### Logging in
 
+You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/discord/authentication.html).
+
 #### Method 1: Login using QR code (recommended)
 
 For using this bridge, you would need to authenticate by **scanning a QR code** with the Discord app on your phone.
@@ -83,26 +85,6 @@ To acquire the token, open Discord in a private browser window. Then open the de
     - for each guild that you'd like bridged, send `guilds bridge GUILD_ID --entire`
 8. You may wish to uninstall the Discord app from your phone now. It's not needed for the bridge to function.
 
-### 💡 Set up Double Puppeting
-
-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 or Shared Secret Auth
-
-The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) or [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service is configured and enabled on the server for this playbook.
-
-Enabling [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.md) 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.
-
-Enabling double puppeting by enabling the [Shared Secret Auth](configuring-playbook-shared-secret-auth.md) service works at the time of writing, but is deprecated and will stop working in the future.
-
-#### 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`
+### Relaying
 
-- make sure you don't log out the `Mautrix-Discord` device some time in the future, as that would break the Double Puppeting feature
+The bridge supports using Discord's webhook feature to relay messages from Matrix users who haven't logged into the bridge. See [the official documentation](https://docs.mau.fi/bridges/go/discord/relay.html#setup) for setting up webhook relaying.