mirror/matrix-docker-ansible-deploy
1
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2025-01-30 11:54:55 +01:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #3973 from luixxiul/patch-2

Browse Source 
Update docs for Draupnir and Mjolnir: misc changes before iteration
This commit is contained in:
Slavi Pantaleev 2025-01-20 09:48:10 +02:00 committed by GitHub
commit 94b10ad446
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
3 changed files with 31 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/configuring-playbook-appservice-draupnir-for-all.md
View File

@ -28,11 +28,7 @@ The management room has to be given an alias, and your bot has to be invited to
This management room is used to control who has access to your D4A deployment. The room stores this data inside of the control room state so your bot must have sufficient powerlevel to send custom state events. This is default 50 or moderator as Element clients call this powerlevel.
As noted in the Draupnir install instructions the control room is sensitive. **Anyone in this room can control the bot so it is important that you only invite trusted users to this room.**
### Set an alias to the management room
Next, set an alias to the management room.
⚠️ **Warning**: anyone in this room can control the bot so it is important that you only invite trusted users to this room.
## Adjusting the playbook configuration

41
docs/configuring-playbook-bot-draupnir.md
View File

@ -6,41 +6,47 @@ See the project's [documentation](https://the-draupnir-project.github.io/draupni
This documentation page is about installing Draupnir in bot mode. As an alternative, you can run a multi-instance Draupnir deployment by installing [Draupnir in appservice mode](./configuring-playbook-appservice-draupnir-for-all.md) (called Draupnir-for-all) instead.
If your migrating from Mjolnir skip to [this section](#migrating-from-mjolnir-only-required-if-migrating).
If your migrating from [Mjolnir](configuring-playbook-bot-mjolnir.md), skip to [this section](#migrating-from-mjolnir-only-required-if-migrating).
## Prerequisites
### Create a management room
Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room.
If you make the management room encrypted (E2EE), then you need to enable the native E2EE support (see [below](#native-e2ee-support)).
⚠️ **Warning**: anyone in this room can control the bot so it is important that you only invite trusted users to this room.
Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element Web you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!qporfwt:example.com`.
It is possible to make the management room encrypted (E2EE). If doing so, then you need to enable the native E2EE support (see [below](#native-e2ee-support)).
Finally invite the `@bot.draupnir:example.com` account that the playbook will create for you to the management room. Please note that clients can issue a warning that your attempting to invite a user that doesnt have a profile and might not exist. This warning is expected as your inviting the bot before its user account exists.
Once you have created the room you need to copy the room ID so you can specify it on your `inventory/host_vars/matrix.example.com/vars.yml` file. In Element Web you can check the ID by going to the room's settings and clicking "Advanced". The room ID will look something like `!qporfwt:example.com`.
## End-to-End Encryption support
Decide whether you want to support having an Encrypted management room or not. Draupnir can still protect encrypted rooms without encryption support enabled.
Decide whether you want to support having an encrypted management room or not. Draupnir can still protect encrypted rooms without encryption support enabled.
Refer to Draupnir's [Documentation](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#protecting-encrypted-rooms) for more information on why you might or might not care about encryption support for protected rooms.
Refer to Draupnir's [documentation](https://the-draupnir-project.github.io/draupnir-documentation/moderator/managing-protected-rooms#protecting-encrypted-rooms) for more details about why you might want to care about encryption support for protected rooms.
**Note**: Draupnir does not support running with Pantalaimon as it would break all workflows that involve answering prompts with reactions.
### Disable Pantalaimon for Draupnir (since v2.0.0; optional)
It is known that running Draupnir along with Pantalaimon breaks all workflows that involve answering prompts with reactions.
If you are updating Draupnir from v1.x.x and have enabled Pantalaimon for it, you can disable Pantalaimon in favor of the native E2EE support. To disable Pantalaimon, remove the configuration `matrix_bot_draupnir_pantalaimon_use: true` from your `vars.yml` file.
**Note**: because the management room is still encrypted, disabling it without enabling the native E2EE support will break the management room.
### Native E2EE support
To enable the native E2EE support, you need to obtain an access token for Draupnir.
To enable the native E2EE support, you need to obtain an access token for Draupnir and set it on your `vars.yml` file.
Note that native E2EE requires a clean access token that has not touched E2EE so curl is recommended as a method to obtain it. **The access token obtained via Element Web does not work with it**. Refer to the documentation on [how to obtain an access token via curl](obtaining-access-tokens.md#obtain-an-access-token-via-curl).
To enable the native E2EE support, add the following configuration to your `vars.yml` file:
```yaml
# Enables the native E2EE Support
# Enables the native E2EE support
matrix_bot_draupnir_enable_experimental_rust_crypto: true
# Access Token the bot uses to login.
# Access token which the bot will use for logging in.
# Comment out `matrix_bot_draupnir_login_native` when using this option.
matrix_bot_draupnir_access_token: "ACCESS_TOKEN_HERE"
```
@ -66,14 +72,15 @@ matrix_bot_draupnir_login_native: true
matrix_bot_draupnir_management_room: "MANAGEMENT_ROOM_ID_HERE"
```
Before Proceeding run the playbook with the following command to make sure the Draupnir user has been created.
Before proceeding to the next step, run the playbook with the following command to make sure that the bot user has been created.
```sh
ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created
```
### Make sure the account is free from rate limiting
### Make sure the account is free from rate limiting (optional, recommended)
If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a heavily recomended step. If you do not configure it, Draupnir performance will be degraded.**
If your homeserver's implementation is Synapse, you will need to prevent it from rate limiting the bot's account. **This is a highly recommended step. If you do not configure it, Draupnir performance will be degraded.**
This can be done using Synapse's [Admin APIs](https://element-hq.github.io/synapse/latest/admin_api/user_admin_api.html#override-ratelimiting-for-users). They can be accessed both externally and internally.
@ -112,7 +119,7 @@ matrix_bot_draupnir_abuse_reporting_enabled: true
<!--
NOTE: this is unsupported by the playbook due to the admin API being inaccessible from containers currently.
The other method polls an Synapse Admin API endpoint, hence it is available only if using Synapse and if the Draupnir user is an admin (see [above](#register-the-bot-account)). To enable it, set `pollReports: true` on `vars.yml` file as below.
The other method polls an Synapse Admin API endpoint, hence it is available only if using Synapse and if the Draupnir user is an admin (see [above](#register-the-bot-account)). To enable it, set `pollReports: true` on `vars.yml` file as below.
-->
### Extending the configuration
@ -141,7 +148,7 @@ matrix_bot_draupnir_configuration_extension_yaml: |
Replace your `matrix_bot_mjolnir` config with `matrix_bot_draupnir` config. Also disable Mjolnir if you're doing migration.
Note that Pantalaimon is unsupported by Draupnir so it is recommended to consult the instructions to enable [the native E2EE support](#native-e2ee-support).
Note that Draupnir supports E2EE natively, so you can enable it instead of Pantalaimon. It is recommended to consult the instruction [here](#native-e2ee-support).
That is all you need to do due to that Draupnir can complete migration on its own.
@ -164,6 +171,8 @@ ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-use
## Usage
To use Draupnir, you need to invite the bot (`@bot.draupnir:example.com`) to its management room which you have created earlier.
You can refer to the upstream [documentation](https://the-draupnir-project.github.io/draupnir-documentation/) for additional ways to use and configure Draupnir and for a more detailed usage guide.
Below is a **non-exhaustive quick-start guide** for the impatient.

8
docs/configuring-playbook-bot-mjolnir.md
View File

@ -52,11 +52,13 @@ You can obtain an access token for a homeserver admin account in the same way as
### Create a management room
Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room. Anyone in this room can control the bot so it is important that you only invite trusted users to this room.
Using your own account, create a new invite only room that you will use to manage the bot. This is the room where you will see the status of the bot and where you will send commands to the bot, such as the command to ban a user from another room.
If you make the management room encrypted (E2EE), then you MUST enable and use Pantalaimon (see [below](#configuration-with-e2ee-support)).
⚠️ **Warning**: anyone in this room can control the bot so it is important that you only invite trusted users to this room.
Once you have created the room you need to copy the room ID so you can tell the bot to use that room. In Element Web you can do this by going to the room's settings, clicking Advanced, and then copying the internal room ID. The room ID will look something like `!qporfwt:example.com`.
It is possible to make the management room encrypted (E2EE). If doing so, then you MUST enable and use Pantalaimon (see [below](#configuration-with-e2ee-support)).
Once you have created the room you need to copy the room ID so you can specify it on your `vars.yml` file. In Element Web you can check the ID by going to the room's settings and clicking "Advanced". The room ID will look something like `!qporfwt:example.com`.
Finally invite the `@bot.mjolnir:example.com` account you created earlier into the room.