self-hosted/matrix-docker-ansible-deploy
1
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2024-11-30 08:16:45 +02:00
Code Issues Releases Activity

Apply the common documentation style (#3840)

Browse Source 
* Update docs/configuring-playbook-bridge-appservice-webhooks.md: apply the common documentation style

Since the bridge has been deprecated, this change is simply intended to improve styling and format of the article in case it will be used as a template of another bridge in a future.

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

* Update docs/configuring-playbook-bridge-appservice-discord.md: apply the common documentation style

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

* Update docs/configuring-playbook-bridge-appservice-slack.md: apply the common documentation style

Also: move instruction to create Classic Slack application up as prerequisite

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

* Update docs/configuring-playbook-bridge-appservice-slack.md: emphasize the unavailability without a classic Slack application

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 2024-11-30 00:52:28 +09:00 committed by GitHub
parent 119e78bc11
commit 45352e76ce
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 173 additions and 173 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
docs/configuring-playbook-bridge-appservice-discord.md
View File

@ -8,38 +8,37 @@ The playbook can install and configure [matrix-appservice-discord](https://githu
See the project's [documentation](https://github.com/matrix-org/matrix-appservice-discord/blob/master/README.md) to learn what it does and why it might be useful to you.
## Prerequisites
## Setup Instructions
Create a Discord Application [here](https://discordapp.com/developers/applications). Then retrieve Client ID, and create a bot from the Bot tab and retrieve the Bot token.
Instructions loosely based on [this](https://github.com/matrix-org/matrix-appservice-discord#setting-up).
## Adjusting the playbook configuration
1. Create a Discord Application [here](https://discordapp.com/developers/applications).
2. Retrieve Client ID.
3. Create a bot from the Bot tab and retrieve the Bot token.
4. Enable the bridge with the following configuration in your `vars.yml` file:
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_appservice_discord_enabled: true
matrix_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
```
```yaml
matrix_appservice_discord_enabled: true
matrix_appservice_discord_client_id: "YOUR DISCORD APP CLIENT ID"
matrix_appservice_discord_bot_token: "YOUR DISCORD APP BOT TOKEN"
5. As of Synapse 1.90.0, you will need to add the following to `matrix_synapse_configuration_extension_yaml` to enable the [backwards compatibility](https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs:
# As of Synapse 1.90.0, uncomment to enable the backwards compatibility (https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs.
# Note: This deprecated method is considered insecure.
#
# matrix_synapse_configuration_extension_yaml: |
# use_appservice_legacy_authorization: true
```
```yaml
matrix_synapse_configuration_extension_yaml: |
use_appservice_legacy_authorization: true
```
## Installing
**Note**: This deprecated method is considered insecure.
After configuring the playbook, run the [installation](installing.md) command:
6. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
Other configuration options are available via the `matrix_appservice_discord_configuration_extension_yaml` variable.
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Self-Service Bridging (Manual)
Self-service bridging allows you to bridge specific and existing Matrix rooms to specific Discord rooms. This is disabled by default, so it must be enabled by adding this to your `vars.yml`:
Self-service bridging allows you to bridge specific and existing Matrix rooms to specific Discord rooms. To enable it, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_appservice_discord_bridge_enableSelfServiceBridging: true
@ -47,27 +46,32 @@ matrix_appservice_discord_bridge_enableSelfServiceBridging: true
**Note**: If self-service bridging is not enabled, `!discord help` commands will return no results.
Once self-service is enabled:
### Usage
1. Start a chat with `@_discord_bot:example.com` and say `!discord help bridge`.
2. Follow the instructions in the help output message. If the bot is not already in the Discord server, follow the provided invite link. This may require you to be a administrator of the Discord server.
Once self-service is enabled, start a chat with `@_discord_bot:example.com` and say `!discord help bridge`.
**Note**: Encrypted Matrix rooms are not supported as of writing.
Then, follow the instructions in the help output message.
If the bot is not already in the Discord server, follow the provided invite link. This may require you to be a administrator of the Discord server.
On the Discord side, you can say `!matrix help` to get a list of available commands to manage the bridge and Matrix users.
**Note**: Encrypted Matrix rooms are not supported as of writing.
## Portal Bridging (Automatic)
Through portal bridging, Matrix rooms will automatically be created by the bot and bridged to the relevant Discord room. This is done by simply joining a room with a specific name pattern (`#_discord_<guildID>_<channelID>`).
All Matrix rooms created this way are **listed publicly** by default, and you will not have admin permissions to change this. To get more control, [make yourself a room Administrator](#getting-administrator-access-in-a-portal-bridged-room). You can then unlist the room from the directory and change the join rules.
If you want to disable portal bridging, set the following in `vars.yml`:
To disable portal bridging, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_appservice_discord_bridge_disablePortalBridging: true
```
### Usage
To get started with Portal Bridging:
1. To invite the bot to Discord, retrieve the invite link from the `{{ matrix_appservice_discord_config_path }}/invite_link` file on the server (this defaults to `/matrix/appservice-discord/config/invite_link`). You need to peek at the file on the server via SSH, etc., because it's not available via HTTP(S).

189
docs/configuring-playbook-bridge-appservice-slack.md
View File

@ -2,135 +2,126 @@
**Notes**:
- Bridging to [Slack](https://slack.com) can also happen via the [mx-puppet-slack](configuring-playbook-bridge-mx-puppet-slack.md) and [mautrix-slack](configuring-playbook-bridge-mautrix-slack.md) bridges supported by the playbook.
- Currently (as of November, 2024) this component is not available for new installation unless you have already created a classic Slack application (which the bridge makes use of in order to enable bridging between Slack and Matrix), because the creation of classic Slack applications has been discontinued since June 4 2024. The author of the bridge claims [here](https://github.com/matrix-org/matrix-appservice-slack/issues/789#issuecomment-2172947787) that he plans to support the modern Slack application and until then "the best (and only) option for new installations is to use the webhook bridging".
- Currently (as of November, 2024) **this component is not available for new installation unless you have already created a classic Slack application** (which the bridge makes use of in order to enable bridging between Slack and Matrix), because the creation of classic Slack applications has been discontinued since June 4 2024. The author of the bridge claims [here](https://github.com/matrix-org/matrix-appservice-slack/issues/789#issuecomment-2172947787) that he plans to support the modern Slack application and until then "the best (and only) option for new installations is to use the webhook bridging".
The playbook can install and configure [matrix-appservice-slack](https://github.com/matrix-org/matrix-appservice-slack) for you.
See the project's [documentation](https://github.com/matrix-org/matrix-appservice-slack/blob/master/README.md) to learn what it does and why it might be useful to you.
## Setup Instructions:
## Prerequisites
loosely based on [this](https://github.com/matrix-org/matrix-appservice-slack#Setup)
### Create a Classic Slack App
1. Create a new Matrix room to act as the administration control room. Note its internal room ID. This can be done in Element Web by sending a message, opening the options for that message and choosing "view source". The room ID will be displayed near the top.
First, you need to create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
2. Enable the bridge by adding the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
Name the app "matrixbot" (or anything else you'll remember). Select the team/workspace this app will belong to. Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
```yaml
matrix_appservice_slack_enabled: true
matrix_appservice_slack_control_room_id: "Your Matrix admin room ID"
```
Then, click on Event Subscriptions and enable them and use the request url: `https://matrix.example.com/appservice-slack`.
3. Enable puppeting (optional, but recommended)
Add the following events as `Bot User Events` and save:
```yaml
matrix_appservice_slack_puppeting_enabled: true
matrix_appservice_slack_puppeting_slackapp_client_id: "Your Classic Slack App Client ID"
matrix_appservice_slack_puppeting_slackapp_client_secret: "Your Classic Slack App Client Secret"
```
- team_domain_change
- message.channels
- message.groups (if you want to bridge private channels)
- reaction_added
- reaction_removed
4. Enable Team Sync (optional)
Next, click on "OAuth & Permissions" and add the following scopes:
```yaml
matrix_appservice_slack_team_sync_enabled: true
```
- chat:write:bot
- users:read
- reactions:write
- files:write:user (if you want to bridge files)
See https://matrix-appservice-slack.readthedocs.io/en/latest/team_sync/
**Note**: In order to make Slack files visible to Matrix users, this bridge will make Slack files visible to anyone with the url (including files in private channels). This is different than the current behavior in Slack, which only allows authenticated access to media posted in private channels. See MSC701 for details.
5. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
Click on "Install App" and "Install App to Workspace". Note the access tokens shown. You will need the Bot User OAuth Access Token and if you want to bridge files, the OAuth Access Token whenever you link a room.
6. Invite the bridge bot user into the admin room:
### Create an administration control room on Matrix
Create a new Matrix room to act as the administration control room.
Note its internal room ID. This can be done in Element Web by sending a message, opening the options for that message and choosing "view source". The room ID will be displayed near the top.
## Adjusting the playbook configuration
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_appservice_slack_enabled: true
matrix_appservice_slack_control_room_id: "Your Matrix admin room ID"
# Uncomment to enable puppeting (optional, but recommended)
# matrix_appservice_slack_puppeting_enabled: true
# matrix_appservice_slack_puppeting_slackapp_client_id: "Your Classic Slack App Client ID"
# matrix_appservice_slack_puppeting_slackapp_client_secret: "Your Classic Slack App Client Secret"
# Uncomment to enable Team Sync (optional)
# See https://matrix-appservice-slack.readthedocs.io/en/latest/team_sync/
# matrix_appservice_slack_team_sync_enabled: true
```
Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
## Installing
After configuring the playbook, run the [installation](installing.md) command:
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
## Usage
Send `/invite @slackbot:example.com` to invite the bridge bot user into the admin room.
If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
- Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like `!qporfwt:example.com`.
- Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @matrixbot` for Slack and `/invite @slackbot:example.com` for Matrix.
- Determine the "channel ID" that Slack uses to identify the channel. You can see it when you open a given Slack channel in a browser. The URL reads like this: `https://app.slack.com/client/XXX/<the channel ID>/details/`.
- Issue a link command in the administration control room with these collected values as arguments:
with file bridging:
```
/invite @slackbot:example.com
link --channel_id CHANNELID --room !qporfwt:example.com --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx --slack_user_token xoxp-xxxxxxxx-xxxxxxxxx-xxxxxxxx-xxxxxxxx
```
Note that the bot's domain is your server's domain **without the `matrix.` prefix.**
7. Create a Classic Slack App [here](https://api.slack.com/apps?new_classic_app=1).
Name the app "matrixbot" (or anything else you'll remember).
Select the team/workspace this app will belong to.
Click on bot users and add a new bot user. We will use this account to bridge the the rooms.
8. Click on Event Subscriptions and enable them and use the request url `https://matrix.example.com/appservice-slack`. Then add the following events and save:
Bot User Events:
- team_domain_change
- message.channels
- message.groups (if you want to bridge private channels)
- reaction_added
- reaction_removed
9. Click on OAuth & Permissions and add the following scopes:
- chat:write:bot
- users:read
- reactions:write
If you want to bridge files, also add the following:
- files:write:user
**Note**: In order to make Slack files visible to Matrix users, this bridge will make Slack files visible to anyone with the url (including files in private channels). This is different than the current behavior in Slack, which only allows authenticated access to media posted in private channels. See MSC701 for details.
10. Click on Install App and Install App to Workspace. Note the access tokens shown. You will need the Bot User OAuth Access Token and if you want to bridge files, the OAuth Access Token whenever you link a room.
11. If Team Sync is not enabled, for each channel you would like to bridge, perform the following steps:
* Create a Matrix room in the usual manner for your client. Take a note of its Matrix room ID - it will look something like !qporfwt:example.com.
* Invite the bot user to both the Slack and Matrix channels you would like to bridge using `/invite @matrixbot` for Slack and `/invite @slackbot:example.com` for Matrix.
* Determine the "channel ID" that Slack uses to identify the channel. You can see it when you open a given Slack channel in a browser. The URL reads like this: `https://app.slack.com/client/XXX/<the channel ID>/details/`.
* Issue a link command in the administration control room with these collected values as arguments:
with file bridging:
```
link --channel_id CHANNELID --room !qporfwt:example.com --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx --slack_user_token xoxp-xxxxxxxx-xxxxxxxxx-xxxxxxxx-xxxxxxxx
```
without file bridging:
```
link --channel_id CHANNELID --room !qporfwt:example.com --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
```
These arguments can be shortened to single-letter forms:
```
link -I CHANNELID -R !qporfwt:example.com -t xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
```
Other configuration options are available via the `matrix_appservice_slack_configuration_extension_yaml` variable.
12. Unlinking
Channels can be unlinked again like this:
without file bridging:
```
unlink --room !qporfwt:example.com
link --channel_id CHANNELID --room !qporfwt:example.com --slack_bot_token xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
```
Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave the bridged Matrix room. So in case you want to re-link later, don't forget to re-invite the slackbot into this room again.
These arguments can be shortened to single-letter forms:
```
link -I CHANNELID -R !qporfwt:example.com -t xoxb-xxxxxxxxxx-xxxxxxxxxxxxxxxxxxxx
```
### Unlinking
Channels can be unlinked again by sending this:
```
unlink --room !qporfwt:example.com
```
Unlinking doesn't only disconnect the bridge, but also makes the slackbot leave the bridged Matrix room. So in case you want to re-link later, don't forget to re-invite the slackbot into this room again.
## Troubleshooting
* As always, check the logs: `journalctl -fu matrix-appservice-slack`
As always, check the logs: `journalctl -fu matrix-appservice-slack`
* Linking: "Room is now pending-name"
### Linking: "Room is now pending-name"
This typically means that you haven't used the correct Slack channel ID. Unlink the room and recheck 'Determine the "channel ID"' from above.
This typically means that you haven't used the correct Slack channel ID. Unlink the room and recheck 'Determine the "channel ID"' from above.
* Messages work from M to S, but not the other way around
### Messages work from Matrix to Slack, but not the other way around
Check you logs, if they say something like
Check you logs, if they say something like
`WARN SlackEventHandler Ignoring message from unrecognised Slack channel ID : %s (%s) <the channel ID> <some other ID>`
`WARN SlackEventHandler Ignoring message from unrecognised Slack channel ID : %s (%s) <the channel ID> <some other ID>`
then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link your room multiple times without unlinking it after each failed attempt.
then unlink your room, reinvite the bot and re-link it again. This may particularly hit you, if you tried to unsuccessfully link your room multiple times without unlinking it after each failed attempt.

101
docs/configuring-playbook-bridge-appservice-webhooks.md
View File

@ -4,70 +4,75 @@
The playbook can install and configure [matrix-appservice-webhooks](https://github.com/turt2live/matrix-appservice-webhooks) for you. This bridge provides support for Slack-compatible webhooks.
Setup Instructions:
See the project's [documentation](https://github.com/turt2live/matrix-appservice-webhooks/blob/master/README.md) to learn what it does and why it might be useful to you.
loosely based on [this](https://github.com/turt2live/matrix-appservice-webhooks/blob/master/README.md)
## Adjusting the playbook configuration
1. Add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
To enable the bridge, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file:
```yaml
matrix_appservice_webhooks_enabled: true
matrix_appservice_webhooks_api_secret: '<your_secret>'
```
```yaml
matrix_appservice_webhooks_enabled: true
matrix_appservice_webhooks_api_secret: '<your_secret>'
2. In case you want to change the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service` you can adjust this in `inventory/host_vars/matrix.example.com/vars.yml` as well.
# Uncomment to increase the verbosity of logging via `journalctl -fu matrix-appservice-webhooks.service`
# matrix_appservice_webhooks_log_level: 'verbose'
**Note**: default value is: `info` and availabe log levels are : `info`, `verbose`
# As of Synapse 1.90.0, uncomment to enable the backwards compatibility (https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs.
# Note: This deprecated method is considered insecure.
#
# matrix_synapse_configuration_extension_yaml: |
# use_appservice_legacy_authorization: true
```
```yaml
matrix_appservice_webhooks_log_level: '<log_level>'
```
## Installing
3. As of Synapse 1.90.0, you will need to add the following to `matrix_synapse_configuration_extension_yaml` to enable the [backwards compatibility](https://matrix-org.github.io/synapse/latest/upgrade#upgrading-to-v1900) that this bridge needs:
After configuring the playbook, run the [installation](installing.md) command:
```yaml
matrix_synapse_configuration_extension_yaml: |
use_appservice_legacy_authorization: true
```
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
```
**Note**: This deprecated method is considered insecure.
## Usage
4. If you've already installed Matrix services using the playbook before, you'll need to re-run it (`--tags=setup-all,start`). If not, proceed with [configuring other playbook services](configuring-playbook.md) and then with [Installing](installing.md). Get back to this guide once ready.
Invite the bridge bot user to your room in either way.
5. If you're using the [Dimension integration manager](configuring-playbook-dimension.md), you can configure the Webhooks bridge by opening the Dimension integration manager -> Settings -> Bridges and selecting edit action for "Webhook Bridge". Press "Add self-hosted Bridge" button and populate "Provisioning URL" & "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively.
- 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)
6. Invite the bridge bot user to your room:
You then need to send a message to the bridge bot in order to receive a private message including the webhook link:
- either with `/invite @_webhook:example.com` (**Note**: Make sure you have administration permissions in your room)
```
!webhook
```
- or simply add the bridge bot to a private channel (personal channels imply you being an administrator)
The JSON body for posting messages will have to look like this:
7. Send a message to the bridge bot in order to receive a private message including the webhook link.
```
!webhook
```
8. The JSON body for posting messages will have to look like this:
```json
{
"text": "Hello world!",
"format": "plain",
"displayName": "My Cool Webhook",
"avatar_url": "http://i.imgur.com/IDOBtEJ.png"
}
```
You can test this via curl like so:
```sh
curl --header "Content-Type: application/json" \
--data '{
```json
{
"text": "Hello world!",
"format": "plain",
"displayName": "My Cool Webhook",
"avatar_url": "http://i.imgur.com/IDOBtEJ.png"
}' \
<the link you've gotten in 5.>
```
}
```
You can test this via curl like so:
```sh
curl --header "Content-Type: application/json" \
--data '{
"text": "Hello world!",
"format": "plain",
"displayName": "My Cool Webhook",
"avatar_url": "http://i.imgur.com/IDOBtEJ.png"
}' \
<the webhook link you've gotten from the bridge bot>
```
### Setting Webhooks with Dimension integration manager
If you're using the [Dimension integration manager](configuring-playbook-dimension.md), you can configure the Webhooks bridge with it.
To configure it, open the Dimension integration manager, and go to "Settings" and "Bridges", then select edit action for "Webhook Bridge".
On the UI, press "Add self-hosted Bridge" button and populate "Provisioning URL" and "Shared Secret" values from `/matrix/appservice-webhooks/config/config.yaml` file's homeserver URL value and provisioning secret value, respectively.