Merge pull request #3902 from luixxiul/fix

spantaleev · web-flow · commit 6a07fb18f76e · 2024-12-23T20:52:49.000+02:00
Edit docs: adopt the common instruction
diff --git 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).
+
+The playbook can install and configure the [Dimension](https://dimension.t2bot.io) integration manager for you.
+
+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, recommended)
+
+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
 
-**Note**: Dimension is **[officially unmaintained](https://github.com/spantaleev/matrix-docker-ansible-deploy/issues/2806#issuecomment-1673559299)**. We recommend not bothering with installing it.
+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).
 
-**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).
+⚠️ **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).
diff --git a/docs/configuring-playbook-email2matrix.md b/docs/configuring-playbook-email2matrix.md
@@ -22,41 +22,52 @@ 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, recommended)
 
-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`.
 
-### Creating a shared room
+You can use the playbook to [register a new user](registering-users.md):
 
-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).
+```sh
+ansible-playbook -i inventory/hosts setup.yml --extra-vars='username=email2matrix password=PASSWORD_FOR_THE_USER admin=no' --tags=register-user
+```
 
-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.
+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.
 
-Inviting additional people to the room is okay too.
+### Obtain an access token
 
-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.
+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).
 
-### Obtain an access token for the sender user
+⚠️ **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.
 
-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).
+### Join to rooms as the sender user manually
 
-⚠️ **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.
+ℹ️ **Email2Matrix does not accept room invitations automatically**. To deliver messages to rooms, the sender user must be joined to all rooms manually.
+
+For each new room you would like the user to deliver messages to, invite the user to the room.
+
+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.
 
 ## 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 +76,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
diff --git 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=<Local IP address of the host>"'
 ```
 
-## (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-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
 
diff --git 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,15 +67,15 @@ 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:
 
 ```yaml
 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
@@ -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.
 
