From 4798888ac7fa0ce5bbe16caaf58361706668a7ae Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 23 Dec 2024 12:14:52 +0900 Subject: [PATCH 1/6] Edit docs/configuring-playbook-dimension.md: adopt the common instruction for introduction and prerequisites - Register a dedicated Matrix user (optional) - Obtain an access token Since Dimension has been archived, this is purely for possible use as a template of another component. Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-dimension.md | 52 ++++++++++++++++---------- 1 file changed, 32 insertions(+), 20 deletions(-) diff --git a/docs/configuring-playbook-dimension.md b/docs/configuring-playbook-dimension.md index 652ed6e83..129911bcd 100644 --- a/docs/configuring-playbook-dimension.md +++ b/docs/configuring-playbook-dimension.md @@ -1,17 +1,45 @@ # Setting up Dimension integration manager (optional, unmaintained) -**[Dimension](https://dimension.t2bot.io) can only be installed after Matrix services are installed and running.** If you're just installing Matrix services for the first time, please continue with the [Configuration](configuring-playbook.md) / [Installation](installing.md) flow and come back here later. +**Notes**: +- Dimension is **[officially unmaintained](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2806#issuecomment-1673559299)**. We recommend not bothering with installing it. +- This playbook now supports running Dimension in both a federated and [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environments. This is handled automatically based on the value of `matrix_homeserver_federation_enabled`. Enabling Dimension, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible). -**Note**: Dimension is **[officially unmaintained](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2806#issuecomment-1673559299)**. We recommend not bothering with installing it. +The playbook can install and configure the [Dimension](https://dimension.t2bot.io) integration manager for you. -**Note**: This playbook now supports running [Dimension](https://dimension.t2bot.io) in both a federated and [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environments. This is handled automatically based on the value of `matrix_homeserver_federation_enabled`. Enabling Dimension, means that the `openid` API endpoints will be exposed on the Matrix Federation port (usually `8448`), even if [federation](configuring-playbook-federation.md) is disabled. It's something to be aware of, especially in terms of firewall whitelisting (make sure port `8448` is accessible). +See the project's [documentation](https://github.com/turt2live/matrix-dimension/blob/master/README.md) to learn what it does and why it might be useful to you. + +## Prerequisites + +### Install Matrix services + +Dimension can only be installed after Matrix services are installed and running. If you're just installing Matrix services for the first time, please continue with the [Configuration](configuring-playbook.md) / [Installation](installing.md) and come back here later. + +### Register a dedicated Matrix user (optional) + +We recommend that you create a dedicated Matrix user for Dimension (`dimension` is a good username). + +Generate a strong password for the user. You can create one with a command like `pwgen -s 64 1`. + +You can use the playbook to [register a new user](registering-users.md): + +```sh +ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=dimension password=PASSWORD_FOR_THE_USER admin=no' --tags=register-user +``` + +### Obtain an access token + +Dimension requires an access token to be able to connect to your homeserver. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). + +⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. ## Adjusting the playbook configuration -To enable Dimension, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`): +To enable Dimension, add this to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`). Make sure to replace `ACCESS_TOKEN_HERE` with the one created [above](#obtain-an-access-token). ```yaml matrix_dimension_enabled: true + +matrix_dimension_access_token: "ACCESS_TOKEN_HERE" ``` ### Define admin users @@ -26,22 +54,6 @@ matrix_dimension_admins: The admin interface is accessible within Element Web by accessing it in any room and clicking the cog wheel/settings icon in the top right. Currently, Dimension can be opened in Element Web by the "Add widgets, bridges, & bots" link in the room information. -### Obtain an access token - -We recommend that you create a dedicated Matrix user for Dimension (`dimension` is a good username). Follow our [Registering users](registering-users.md) guide to learn how to register **a regular (non-admin) user**. - -You are required to specify an access token (belonging to this new user) for Dimension to work. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). - -⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. - -Add access token to your configuration file (`inventory/host_vars/matrix.example.com/vars.yml`): - -```yaml -matrix_dimension_access_token: "YOUR ACCESS TOKEN HERE" -``` - -For more information on how to acquire an access token, visit [https://t2bot.io/docs/access_tokens](https://t2bot.io/docs/access_tokens). - ### Adjusting the Dimension URL By default, this playbook installs Dimension on the `dimension.` subdomain (`dimension.example.com`) and requires you to [adjust your DNS records](#adjusting-dns-records). From 2c80aaf980764d4b96f2f80305331f49c2d7b411 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 23 Dec 2024 12:21:31 +0900 Subject: [PATCH 2/6] Edit docs/configuring-playbook-email2matrix.md: adopt the common instruction Based on docs/configuring-playbook-dimension.md and docs/configuring-playbook-bot-go-neb.md Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-email2matrix.md | 33 ++++++++++++++--------- 1 file changed, 21 insertions(+), 12 deletions(-) diff --git a/docs/configuring-playbook-email2matrix.md b/docs/configuring-playbook-email2matrix.md index f57904986..533576bab 100644 --- a/docs/configuring-playbook-email2matrix.md +++ b/docs/configuring-playbook-email2matrix.md @@ -22,11 +22,25 @@ If you really need to run an email server on the Matrix machine for other purpos For details about using Email2Matrix alongside [Postfix](http://www.postfix.org/), see [here](https://github.com/devture/email2matrix/blob/master/docs/setup_with_postfix.md). -### Creating a user +### Register a dedicated Matrix user (optional) -Before enabling Email2Matrix, you'd most likely wish to create a dedicated user (or more) that would be sending messages on the Matrix side. Take note of the user's ID as it needs to be specified as `MatrixUserId` on your `inventory/host_vars/matrix.example.com/vars.yml` file later. +We recommend that you create a dedicated Matrix user for Email2Matrix. -Refer to [Registering users](registering-users.md) for ways to create a user. A regular (non-admin) user works best. +Generate a strong password for the user. You can create one with a command like `pwgen -s 64 1`. + +You can use the playbook to [register a new user](registering-users.md): + +```sh +ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=email2matrix password=PASSWORD_FOR_THE_USER admin=no' --tags=register-user +``` + +Take note of the user's ID as it needs to be specified as `MatrixUserId` on your `inventory/host_vars/matrix.example.com/vars.yml` file later. + +### Obtain an access token + +Email2Matrix requires an access token for the sender user to be able to send messages to the room. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). + +⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. ### Creating a shared room @@ -38,25 +52,20 @@ Inviting additional people to the room is okay too. Take note of each room's room ID (different clients show the room ID in a different place). You'll need the room ID when [configuring the playbook](#adjusting-the-playbook-configuration) below. -### Obtain an access token for the sender user - -In order for the sender user created above to be able to send messages to the room, we'll need to obtain an access token for it. Refer to the documentation on [how to obtain an access token](obtaining-access-tokens.md). - -⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. - ## Adjusting the playbook configuration -After doing the preparation steps above, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file (adapt to your needs): +To enable Email2Matrix, add the following configuration to your `inventory/host_vars/matrix.example.com/vars.yml` file. Make sure to replace `ACCESS_TOKEN_FOR_EMAIL2MATRIX1_HERE` and `ACCESS_TOKEN_FOR_EMAIL2MATRIX2_HERE` with the ones created [above](#obtain-an-access-token). ```yaml matrix_email2matrix_enabled: true +# You need at least 1 mailbox. matrix_email2matrix_matrix_mappings: - MailboxName: "mailbox1" MatrixRoomId: "!qporfwt:{{ matrix_domain }}" MatrixHomeserverUrl: "{{ matrix_homeserver_url }}" MatrixUserId: "@email2matrix1:{{ matrix_domain }}" - MatrixAccessToken: "MATRIX_ACCESS_TOKEN_HERE" + MatrixAccessToken: "ACCESS_TOKEN_FOR_EMAIL2MATRIX1_HERE" IgnoreSubject: false IgnoreBody: false SkipMarkdown: false @@ -65,7 +74,7 @@ matrix_email2matrix_matrix_mappings: MatrixRoomId: "!aaabaa:{{ matrix_domain }}" MatrixHomeserverUrl: "{{ matrix_homeserver_url }}" MatrixUserId: "@email2matrix2:{{ matrix_domain }}" - MatrixAccessToken: "MATRIX_ACCESS_TOKEN_HERE" + MatrixAccessToken: "ACCESS_TOKEN_FOR_EMAIL2MATRIX2_HERE" IgnoreSubject: true IgnoreBody: false SkipMarkdown: true From a2b92432470ccbf38cbc87b419d6c3a1da82d5c5 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 23 Dec 2024 13:07:56 +0900 Subject: [PATCH 3/6] Edit docs/configuring-playbook-email2matrix.md: adopt the common instruction about registering a dedicated user Based on docs/configuring-playbook-alertmanager-receiver.md Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-email2matrix.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/configuring-playbook-email2matrix.md b/docs/configuring-playbook-email2matrix.md index 533576bab..8bbc9f1a8 100644 --- a/docs/configuring-playbook-email2matrix.md +++ b/docs/configuring-playbook-email2matrix.md @@ -42,13 +42,15 @@ Email2Matrix requires an access token for the sender user to be able to send mes ⚠️ **Warning**: Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone. -### Creating a shared room +### Join to rooms as the sender user manually -After creating the sender user, you should create one or more Matrix rooms that you share with that user. It doesn't matter who creates and owns the rooms and who joins later (you or the sender user). +ℹ️ **Email2Matrix does not accept room invitations automatically**. To deliver messages to rooms, the sender user must be joined to all rooms manually. -What matters is that both you and the sender user are part of the same room and that the sender user has enough privileges in the room to be able to send messages there. +For each new room you would like the user to deliver messages to, invite the user to the room. -Inviting additional people to the room is okay too. +Then, log in as the sender user using any Matrix client of your choosing, accept the room invitation from the user's account. + +Make sure that you and the sender user are part of the same room and that the sender user has enough privileges in the room to be able to send messages there, then log out. Take note of each room's room ID (different clients show the room ID in a different place). You'll need the room ID when [configuring the playbook](#adjusting-the-playbook-configuration) below. From 362d9cabd8c65350a56af86e08d32c5f4beb726a Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 23 Dec 2024 15:06:46 +0900 Subject: [PATCH 4/6] Update docs: add "recommended" to the "optional" label on the headers Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-dimension.md | 2 +- docs/configuring-playbook-email2matrix.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/configuring-playbook-dimension.md b/docs/configuring-playbook-dimension.md index 129911bcd..5e7e86b15 100644 --- a/docs/configuring-playbook-dimension.md +++ b/docs/configuring-playbook-dimension.md @@ -14,7 +14,7 @@ See the project's [documentation](https://github.com/turt2live/matrix-dimension/ Dimension can only be installed after Matrix services are installed and running. If you're just installing Matrix services for the first time, please continue with the [Configuration](configuring-playbook.md) / [Installation](installing.md) and come back here later. -### Register a dedicated Matrix user (optional) +### Register a dedicated Matrix user (optional, recommended) We recommend that you create a dedicated Matrix user for Dimension (`dimension` is a good username). diff --git a/docs/configuring-playbook-email2matrix.md b/docs/configuring-playbook-email2matrix.md index 8bbc9f1a8..86a1052b2 100644 --- a/docs/configuring-playbook-email2matrix.md +++ b/docs/configuring-playbook-email2matrix.md @@ -22,7 +22,7 @@ If you really need to run an email server on the Matrix machine for other purpos For details about using Email2Matrix alongside [Postfix](http://www.postfix.org/), see [here](https://github.com/devture/email2matrix/blob/master/docs/setup_with_postfix.md). -### Register a dedicated Matrix user (optional) +### Register a dedicated Matrix user (optional, recommended) We recommend that you create a dedicated Matrix user for Email2Matrix. From 40ef348c485dfea9b087bcf80a72489b264d694d Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Tue, 24 Dec 2024 00:11:00 +0900 Subject: [PATCH 5/6] Update docs: Move "(optional)" on headers to the end of the line Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-jitsi.md | 12 ++++++------ ...configuring-playbook-user-verification-service.md | 6 +++--- docs/configuring-well-known.md | 2 +- 3 files changed, 10 insertions(+), 10 deletions(-) diff --git a/docs/configuring-playbook-jitsi.md b/docs/configuring-playbook-jitsi.md index dcb0a4232..69b93906b 100644 --- a/docs/configuring-playbook-jitsi.md +++ b/docs/configuring-playbook-jitsi.md @@ -40,7 +40,7 @@ Once you've decided on the domain and path, **you may need to adjust your DNS** By default, you will need to create a CNAME record for `jitsi`. See [Configuring DNS](configuring-dns.md) for details about DNS changes. -## (Optional) Configure Jitsi authentication and guests mode +## Configure Jitsi authentication and guests mode (optional) By default the Jitsi Meet instance does not require any kind of login and is open to use for anyone without registration. @@ -112,7 +112,7 @@ jitsi_ldap_start_tls: false For more information refer to the [docker-jitsi-meet](https://github.com/jitsi/docker-jitsi-meet#authentication-using-ldap) and the [saslauthd `LDAP_SASLAUTHD`](https://github.com/winlibs/cyrus-sasl/blob/master/saslauthd/LDAP_SASLAUTHD) documentation. -## (Optional) Making your Jitsi server work on a LAN +## Making your Jitsi server work on a LAN (optional) By default the Jitsi Meet instance does not work with a client in LAN (Local Area Network), even if others are connected from WAN. There are no video and audio. In the case of WAN to WAN everything is ok. @@ -127,7 +127,7 @@ jitsi_jvb_container_extra_arguments: - '--env "JVB_ADVERTISE_IPS="' ``` -## (Optional) Fine tune Jitsi +## Fine tune Jitsi (optional) Sample **additional** `inventory/host_vars/matrix.example.com/vars.yml` configuration to save up resources (explained below): @@ -152,7 +152,7 @@ You may want to **limit the number of video feeds forwarded to each client**, to You may want to **limit the maximum video resolution**, to save up resources on both server and clients. -## (Optional) Specify a Max number of participants on a Jitsi conference +## Specify a Max number of participants on a Jitsi conference (optional) The playbook allows a user to set a max number of participants allowed to join a Jitsi conference. By default there is no limit. @@ -162,7 +162,7 @@ In order to set the max number of participants use the following **additional** jitsi_prosody_max_participants: 4 # example value ``` -## (Optional) Additional JVBs +## Additional JVBs (optional) By default, a single JVB ([Jitsi VideoBridge](https://github.com/jitsi/jitsi-videobridge)) is deployed on the same host as the Matrix server. To allow more video-conferences to happen at the same time, you may need to provision additional JVB services on other hosts. @@ -253,7 +253,7 @@ traefik_provider_configuration_extension_yaml: | {% endfor %} ``` -## (Optional) Enable Gravatar +## Enable Gravatar (optional) In the default Jisti Meet configuration, gravatar.com is enabled as an avatar service. This results in third party request leaking data to gravatar. Since Element clients already send the url of configured Matrix avatars to Jitsi, we disabled gravatar. diff --git a/docs/configuring-playbook-user-verification-service.md b/docs/configuring-playbook-user-verification-service.md index 6a8dfccb9..09e5ae1dd 100644 --- a/docs/configuring-playbook-user-verification-service.md +++ b/docs/configuring-playbook-user-verification-service.md @@ -53,7 +53,7 @@ You are required to specify an access token (belonging to this new user) for UVS matrix_user_verification_service_uvs_access_token: "YOUR ACCESS TOKEN HERE" ``` -### (Optional) Custom Auth Token +### Custom Auth Token (optional) It is possible to set an API Auth Token to restrict access to the UVS. If this is enabled, anyone making a request to UVS must provide it via the header "Authorization: Bearer TOKEN" @@ -67,7 +67,7 @@ matrix_user_verification_service_uvs_auth_token: "TOKEN" In case Jitsi is also managed by this playbook and 'matrix' authentication in Jitsi is enabled, this collection will automatically configure Jitsi to use the configured auth token. -### (Optional) Disable Auth +### Disable Auth (optional) Authorization is enabled by default. To disable it, add the following configuration to your `vars.yml` file: @@ -75,7 +75,7 @@ Authorization is enabled by default. To disable it, add the following configurat matrix_user_verification_service_uvs_require_auth: false ``` -### (Optional) Federation +### Federation (optional) In theory (however currently untested), UVS can handle federation. To enable it, add the following configuration to your `vars.yml` file: diff --git a/docs/configuring-well-known.md b/docs/configuring-well-known.md index ad9a231dc..9c8e9bef8 100644 --- a/docs/configuring-well-known.md +++ b/docs/configuring-well-known.md @@ -34,7 +34,7 @@ As [per the Client-Server specification](https://matrix.org/docs/spec/client_ser However, this playbook installs your Matrix server on another domain (e.g. `matrix.example.com`) and not on the base domain (e.g. `example.com`), so it takes a little extra manual effort to set up the file. -### (Optional) Support Service Discovery +### Support Service Discovery (optional) [MSC 1929](https://github.com/matrix-org/matrix-spec-proposals/pull/1929), which was added to [Matrix Specification version v1.10](https://spec.matrix.org/v1.10/client-server-api/#getwell-knownmatrixsupport), specifies a way to add contact details of admins, as well as a link to a support page for users who are having issues with the service. Automated services may also index this information and use it for abuse reports, etc. From 516a0035c878207b713bb42c9343088587479d89 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Mon, 23 Dec 2024 14:38:34 +0900 Subject: [PATCH 6/6] Update docs/configuring-playbook-matrix-media-repo.md: replace an external anchor link with an internal one Signed-off-by: Suguru Hirahara --- docs/configuring-playbook-matrix-media-repo.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/configuring-playbook-matrix-media-repo.md b/docs/configuring-playbook-matrix-media-repo.md index 755c27281..4a9c31372 100644 --- a/docs/configuring-playbook-matrix-media-repo.md +++ b/docs/configuring-playbook-matrix-media-repo.md @@ -88,7 +88,7 @@ matrix_media_repo_datastore_s3_opts_bucket_name: "your-media-bucket" ``` -Full list of configuration options with documentation can be found in [`roles/custom/matrix-media-repo/defaults/main.yml`](https://github.com/spantaleev/matrix-docker-ansible-deploy/blob/master/roles/custom/matrix-media-repo/defaults/main.yml) +Full list of configuration options with documentation can be found in [`roles/custom/matrix-media-repo/defaults/main.yml`](../roles/custom/matrix-media-repo/defaults/main.yml) ## Signing Keys