From f90fb61d459905a24a142dd3e62ddc5c7dd0f771 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 29 Dec 2024 13:01:30 -0500 Subject: [PATCH] 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 --- ...iguring-playbook-bridge-mautrix-discord.md | 7 ++-- ...guring-playbook-bridge-mautrix-facebook.md | 35 ++----------------- ...uring-playbook-bridge-mautrix-gmessages.md | 6 ++++ ...ring-playbook-bridge-mautrix-googlechat.md | 6 ++++ ...guring-playbook-bridge-mautrix-hangouts.md | 6 ++++ ...uring-playbook-bridge-mautrix-instagram.md | 28 ++------------- ...-playbook-bridge-mautrix-meta-instagram.md | 6 +++- ...-playbook-bridge-mautrix-meta-messenger.md | 6 ++++ ...figuring-playbook-bridge-mautrix-signal.md | 6 +++- ...nfiguring-playbook-bridge-mautrix-slack.md | 9 ++--- ...guring-playbook-bridge-mautrix-telegram.md | 6 ++++ ...iguring-playbook-bridge-mautrix-twitter.md | 6 ++++ ...guring-playbook-bridge-mautrix-whatsapp.md | 6 ++++ ...iguring-playbook-bridge-mautrix-wsproxy.md | 6 ++++ 14 files changed, 69 insertions(+), 70 deletions(-) diff --git a/docs/configuring-playbook-bridge-mautrix-discord.md b/docs/configuring-playbook-bridge-mautrix-discord.md index df93b246c..e5c948bf8 100644 --- a/docs/configuring-playbook-bridge-mautrix-discord.md +++ b/docs/configuring-playbook-bridge-mautrix-discord.md @@ -30,14 +30,11 @@ 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 +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. ## Installing diff --git a/docs/configuring-playbook-bridge-mautrix-facebook.md b/docs/configuring-playbook-bridge-mautrix-facebook.md index a0d55b62b..eba523a2b 100644 --- a/docs/configuring-playbook-bridge-mautrix-facebook.md +++ b/docs/configuring-playbook-bridge-mautrix-facebook.md @@ -20,40 +20,11 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_mautrix_facebook_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_mautrix_facebook_configuration_extension_yaml: | - bridge: - encryption: - allow: true - default: true -``` - -If you would like to be able to administrate the bridge from your account it can be configured like this: - -```yaml -matrix_mautrix_facebook_configuration_extension_yaml: | - bridge: - permissions: - '@alice:{{ matrix_domain }}': admin -``` - -Using both would look like - -```yaml -matrix_mautrix_facebook_configuration_extension_yaml: | - bridge: - permissions: - '@alice:{{ matrix_domain }}': admin - encryption: - allow: true - default: true -``` - -You may wish to look at `roles/custom/matrix-bridge-mautrix-facebook/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-facebook/defaults/main.yml` to find other things you would like to configure. +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. ## Installing diff --git a/docs/configuring-playbook-bridge-mautrix-gmessages.md b/docs/configuring-playbook-bridge-mautrix-gmessages.md index 40305e06b..8564f76dd 100644 --- a/docs/configuring-playbook-bridge-mautrix-gmessages.md +++ b/docs/configuring-playbook-bridge-mautrix-gmessages.md @@ -18,6 +18,12 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_mautrix_gmessages_enabled: true ``` +### Extending the configuration + +There are some additional things you may wish to configure about the 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), [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. + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: diff --git a/docs/configuring-playbook-bridge-mautrix-googlechat.md b/docs/configuring-playbook-bridge-mautrix-googlechat.md index 2b077dfcf..7818b898c 100644 --- a/docs/configuring-playbook-bridge-mautrix-googlechat.md +++ b/docs/configuring-playbook-bridge-mautrix-googlechat.md @@ -18,6 +18,12 @@ To enable the [Google Chat](https://chat.google.com/) bridge, add the following matrix_mautrix_googlechat_enabled: true ``` +### Extending the configuration + +There are some additional things you may wish to configure about the 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), [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. + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: diff --git a/docs/configuring-playbook-bridge-mautrix-hangouts.md b/docs/configuring-playbook-bridge-mautrix-hangouts.md index e2a808ec3..bcdf9c3ea 100644 --- a/docs/configuring-playbook-bridge-mautrix-hangouts.md +++ b/docs/configuring-playbook-bridge-mautrix-hangouts.md @@ -20,6 +20,12 @@ To enable the [Google Hangouts](https://hangouts.google.com/) bridge, add the fo matrix_mautrix_hangouts_enabled: true ``` +### Extending the configuration + +There are some additional things you may wish to configure about the 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), [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. + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: diff --git a/docs/configuring-playbook-bridge-mautrix-instagram.md b/docs/configuring-playbook-bridge-mautrix-instagram.md index 0e16c7eba..14ce9cc63 100644 --- a/docs/configuring-playbook-bridge-mautrix-instagram.md +++ b/docs/configuring-playbook-bridge-mautrix-instagram.md @@ -14,33 +14,11 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_mautrix_instagram_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_mautrix_instagram_configuration_extension_yaml: | - bridge: - encryption: - allow: true - default: true -``` - -If you would like to be able to administrate the bridge from your account it can be configured like this: - -```yaml -# The easy way. The specified Matrix user ID will be made an admin of all bridges -matrix_admin: "@alice:{{ matrix_domain }}" - -# OR: -# The more verbose way. Applies to this bridge only. You may define multiple Matrix users as admins. -matrix_mautrix_instagram_configuration_extension_yaml: | - bridge: - permissions: - '@alice:{{ matrix_domain }}': admin -``` - -You may wish to look at `roles/custom/matrix-bridge-mautrix-instagram/templates/config.yaml.j2` and `roles/custom/matrix-bridge-mautrix-instagram/defaults/main.yml` to find other things you would like to configure. +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. ## Installing diff --git a/docs/configuring-playbook-bridge-mautrix-meta-instagram.md b/docs/configuring-playbook-bridge-mautrix-meta-instagram.md index 6514cac90..e04cf73bf 100644 --- a/docs/configuring-playbook-bridge-mautrix-meta-instagram.md +++ b/docs/configuring-playbook-bridge-mautrix-meta-instagram.md @@ -65,7 +65,11 @@ matrix_mautrix_meta_instagram_bridge_permissions_custom: '@alice:{{ matrix_domain }}': admin ``` -You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-instagram/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure. +### Extending the configuration + +There are some additional things you may wish to configure about the 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), [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. ## Installing diff --git a/docs/configuring-playbook-bridge-mautrix-meta-messenger.md b/docs/configuring-playbook-bridge-mautrix-meta-messenger.md index 9e40720bb..f3d4893c5 100644 --- a/docs/configuring-playbook-bridge-mautrix-meta-messenger.md +++ b/docs/configuring-playbook-bridge-mautrix-meta-messenger.md @@ -80,6 +80,12 @@ matrix_mautrix_meta_messenger_bridge_permissions_custom: You may wish to look at `roles/custom/matrix-bridge-mautrix-meta-messenger/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure. +### Extending the configuration + +There are some additional things you may wish to configure about the 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), [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. + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: diff --git a/docs/configuring-playbook-bridge-mautrix-signal.md b/docs/configuring-playbook-bridge-mautrix-signal.md index b925a2bc2..a65b15b7c 100644 --- a/docs/configuring-playbook-bridge-mautrix-signal.md +++ b/docs/configuring-playbook-bridge-mautrix-signal.md @@ -65,7 +65,11 @@ matrix_mautrix_signal_bridge_permissions: '@bob:{{ matrix_domain }}' : user ``` -You may wish to look at `roles/custom/matrix-bridge-mautrix-signal/templates/config.yaml.j2` to find more information on the permissions settings and other options you would like to configure. +### Extending the configuration + +There are some additional things you may wish to configure about the 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), [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. ## Installing diff --git a/docs/configuring-playbook-bridge-mautrix-slack.md b/docs/configuring-playbook-bridge-mautrix-slack.md index dd2ee5342..260e5a427 100644 --- a/docs/configuring-playbook-bridge-mautrix-slack.md +++ b/docs/configuring-playbook-bridge-mautrix-slack.md @@ -32,14 +32,11 @@ matrix_mautrix_slack_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 options you may wish to configure with the bridge. +There are some additional things you may wish to configure about the bridge. -Take a look at: - -- `roles/custom/matrix-bridge-mautrix-slack/defaults/main.yml` for some variables that you can customize via your `vars.yml` file -- `roles/custom/matrix-bridge-mautrix-slack/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_slack_configuration_extension_yaml` variable +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. ## Installing diff --git a/docs/configuring-playbook-bridge-mautrix-telegram.md b/docs/configuring-playbook-bridge-mautrix-telegram.md index c48820b38..a43e19317 100644 --- a/docs/configuring-playbook-bridge-mautrix-telegram.md +++ b/docs/configuring-playbook-bridge-mautrix-telegram.md @@ -26,6 +26,12 @@ matrix_mautrix_telegram_api_id: YOUR_TELEGRAM_APP_ID matrix_mautrix_telegram_api_hash: YOUR_TELEGRAM_API_HASH ``` +### Extending the configuration + +There are some additional things you may wish to configure about the 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), [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. + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: diff --git a/docs/configuring-playbook-bridge-mautrix-twitter.md b/docs/configuring-playbook-bridge-mautrix-twitter.md index 81813d2d1..602db3c8b 100644 --- a/docs/configuring-playbook-bridge-mautrix-twitter.md +++ b/docs/configuring-playbook-bridge-mautrix-twitter.md @@ -22,6 +22,12 @@ To enable the bridge, add the following configuration to your `inventory/host_va matrix_mautrix_twitter_enabled: true ``` +### Extending the configuration + +There are some additional things you may wish to configure about the 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), [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. + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: diff --git a/docs/configuring-playbook-bridge-mautrix-whatsapp.md b/docs/configuring-playbook-bridge-mautrix-whatsapp.md index 2fa6e9914..b7fe36cb3 100644 --- a/docs/configuring-playbook-bridge-mautrix-whatsapp.md +++ b/docs/configuring-playbook-bridge-mautrix-whatsapp.md @@ -34,6 +34,12 @@ matrix_mautrix_whatsapp_bridge_relay_admin_only: false If you want to activate the relay bot in a room, send `!wa set-relay`. To deactivate, send `!wa unset-relay`. +### Extending the configuration + +There are some additional things you may wish to configure about the 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), [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. + ## Installing After configuring the playbook, run it with [playbook tags](playbook-tags.md) as below: diff --git a/docs/configuring-playbook-bridge-mautrix-wsproxy.md b/docs/configuring-playbook-bridge-mautrix-wsproxy.md index 9a057391e..fcbe7372f 100644 --- a/docs/configuring-playbook-bridge-mautrix-wsproxy.md +++ b/docs/configuring-playbook-bridge-mautrix-wsproxy.md @@ -20,6 +20,12 @@ matrix_mautrix_wsproxy_syncproxy_shared_secret: 'secret token from bridge' Note that the tokens must match what is compiled into the [mautrix-imessage](https://github.com/mautrix/imessage) bridge running on your Mac or Android device. +### Extending the configuration + +There are some additional things you may wish to configure about the 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), [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. + ### Adjusting the wsproxy URL By default, this playbook installs wsproxy on the `wsproxy.` subdomain (`wsproxy.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records).