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 <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: add the sections 'extending the configuration' Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * 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 <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: edit the top section Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * 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 <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: common section for setting up Double Puppetting Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * 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 <acioustick@noreply.codeberg.org> * 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 <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: add sections for enabling double puppeting Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: adopt common descriptions about bridge permissions Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * 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 <acioustick@noreply.codeberg.org> * 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 <acioustick@noreply.codeberg.org> * 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 <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: add notes about double puppeting with the Shared Secret Auth Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: remove redundant descriptions Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * 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 <acioustick@noreply.codeberg.org> * 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 <acioustick@noreply.codeberg.org> * 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 <acioustick@noreply.codeberg.org> * Update docs for mautrix bridges: add a header for the reference to the common guide Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * 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 <acioustick@noreply.codeberg.org> * 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 <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: add a note about variable names Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> * Update docs/configuring-playbook-bridge-beeper-linkedin.md: re-add the section for instruction about appservice double puppeting 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>
This commit is contained in:
Suguru Hirahara
GitHub
@ -1,7 +1,11 @@
|
||||
# Setting up Messenger bridging via Mautrix Meta (optional)
|
||||
|
||||
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
|
||||
|
||||
The playbook can install and configure the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge for you.
|
||||
|
||||
See the project's [documentation](https://docs.mau.fi/bridges/go/meta/index.html) to learn what it does and why it might be useful to you.
|
||||
|
||||
Since this bridge component can bridge to both [Messenger](https://messenger.com/) and [Instagram](https://instagram.com/) and you may wish to do both at the same time, the playbook makes it available via 2 different Ansible roles (`matrix-bridge-mautrix-meta-messenger` and `matrix-bridge-mautrix-meta-instagram`). The latter is a reconfigured copy of the first one (created by `just rebuild-mautrix-meta-instagram` and `bin/rebuild-mautrix-meta-instagram.sh`).
|
||||
|
||||
This documentation page only deals with the bridge's ability to bridge to Facebook Messenger. For bridging to Instagram, see [Setting up Instagram bridging via Mautrix Meta](configuring-playbook-bridge-mautrix-meta-instagram.md).
|
||||
@ -22,7 +26,7 @@ Then, consider disabling the old bridge in your configuration, so it won't recre
|
||||
|
||||
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) 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.
|
||||
|
||||
## Adjusting the playbook configuration
|
||||
|
||||
@ -48,37 +52,11 @@ You may switch the mode via the `matrix_mautrix_meta_messenger_meta_mode` variab
|
||||
|
||||
Note that switching the mode (especially between `facebook*` and `messenger`) will intentionally make the bridge use another database (`matrix_mautrix_meta_facebook` or `matrix_mautrix_meta_messenger`) to isolate the 2 instances. Switching between Tor and non-Tor may be possible without dataloss, but your mileage may vary. Before switching to a new mode, you may wish to de-configure the old one (send `help` to the bridge bot and unbridge your portals, etc.).
|
||||
|
||||
### Bridge permissions
|
||||
### Extending the configuration
|
||||
|
||||
By default, any user on your homeserver will be able to use the bridge.
|
||||
There are some additional things you may wish to configure about the bridge.
|
||||
|
||||
Different levels of permission can be granted to users:
|
||||
|
||||
- `relay` - Allowed to be relayed through the bridge, no access to commands
|
||||
- `user` - Use the bridge with puppeting
|
||||
- `admin` - Use and administer the bridge
|
||||
|
||||
The permissions are following the sequence: nothing < `relay` < `user` < `admin`.
|
||||
|
||||
The default permissions are set via `matrix_mautrix_meta_messenger_bridge_permissions_default` and are somewhat like this:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_meta_messenger_bridge_permissions_default:
|
||||
'*': relay
|
||||
example.com: user
|
||||
'{{ matrix_admin }}': admin
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
You may redefine `matrix_mautrix_meta_messenger_bridge_permissions_default` any way you see fit, or add extra permissions using `matrix_mautrix_meta_messenger_bridge_permissions_custom` like this:
|
||||
|
||||
```yaml
|
||||
matrix_mautrix_meta_messenger_bridge_permissions_custom:
|
||||
'@alice:{{ matrix_domain }}': admin
|
||||
```
|
||||
|
||||
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.
|
||||
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
|
||||
|
||||
@ -101,28 +79,8 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
|
||||
|
||||
To use the bridge, you need to start a chat with `@messengerbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain). Note that the user ID of the bridge's bot is not `@facebookbot:example.com`.
|
||||
|
||||
You then need to send a `login` command and follow the bridge bot's instructions.
|
||||
You then need to send `login` to the bridge bot and follow the instructions.
|
||||
|
||||
Given that the bot is configured in `messenger` [bridge mode](#bridge-mode) by default, you will need to log in to [messenger.com](https://messenger.com/) (not `facebook.com`!) and obtain the cookies from there as per [the bridge's authentication instructions](https://docs.mau.fi/bridges/go/meta/authentication.html).
|
||||
|
||||
### 💡 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
|
||||
|
||||
The bridge automatically performs Double Puppeting if [Appservice Double Puppet](configuring-playbook-appservice-double-puppet.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 session for which you obtained an access token some time in the future, as that would break the Double Puppeting feature
|
||||
You can learn more here about authentication from the bridge's [official documentation on Authentication](https://docs.mau.fi/bridges/go/meta/authentication.html).
|
||||
|
||||
Reference in New Issue
Block a user