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,16 +1,22 @@
|
||||
# Setting up Mautrix Facebook bridging (optional, deprecated)
|
||||
|
||||
<sup>Refer the common guide for configuring mautrix bridges: [Setting up a Generic Mautrix Bridge](configuring-playbook-bridge-mautrix-bridges.md)</sup>
|
||||
|
||||
**Note**: This bridge has been deprecated in favor of the [mautrix-meta](https://github.com/mautrix/meta) Messenger/Instagram bridge, which can be installed using [this playbook](configuring-playbook-bridge-mautrix-meta-messenger.md). Consider using that bridge instead of this one.
|
||||
|
||||
The playbook can install and configure [mautrix-facebook](https://github.com/mautrix/facebook) for you.
|
||||
|
||||
See the project's [documentation](https://github.com/mautrix/facebook/blob/master/ROADMAP.md) to learn what it does and why it might be useful to you.
|
||||
See the project's [documentation](https://github.com/mautrix/facebook/blob/master/README.md) to learn what it does and why it might be useful to you.
|
||||
|
||||
## 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,40 +26,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
|
||||
|
||||
@ -76,32 +53,10 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
|
||||
|
||||
To use the bridge, you need to start a chat with `@facebookbot:example.com` (where `example.com` is your base domain, not the `matrix.` domain).
|
||||
|
||||
Send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account.
|
||||
You then need to send `login YOUR_FACEBOOK_EMAIL_ADDRESS` to the bridge bot to enable bridging for your Facebook Messenger account.
|
||||
|
||||
If you run into trouble, check the [Troubleshooting](#troubleshooting) section below.
|
||||
|
||||
### 💡 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 `Mautrix-Facebook` device some time in the future, as that would break the Double Puppeting feature
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Facebook rejecting login attempts and forcing you to change password
|
||||
|
||||
Reference in New Issue
Block a user