diff --git a/docs/configuring-playbook-dimension.md b/docs/configuring-playbook-dimension.md index 24fd16e11..d4de8e2b1 100644 --- a/docs/configuring-playbook-dimension.md +++ b/docs/configuring-playbook-dimension.md @@ -4,11 +4,14 @@ 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. ## Prerequisites + This playbook now supports running [Dimension](https://dimension.t2bot.io) in both a federated and an [unfederated](https://github.com/turt2live/matrix-dimension/blob/master/docs/unfederated.md) environment. This is handled automatically based on the value of `matrix_synapse_federation_enabled`. Other important prerequisite is the `dimension.` DNS record being set up correctly. See [Configuring your DNS server](configuring-dns.md) on how to set up DNS record correctly. + ## Enable + [Dimension integrations manager](https://dimension.t2bot.io) installation is disabled by default. You can enable it in your configuration file (`inventory/host_vars/matrix./vars.yml`): ```yaml @@ -17,6 +20,7 @@ matrix_dimension_enabled: true ## Define admin users + These users can modify the integrations this Dimension supports. Admin interface is accessible by opening Dimension in Riot and clicking the settings icon. Add this to your configuration file (`inventory/host_vars/matrix./vars.yml`): @@ -26,16 +30,21 @@ matrix_dimension_admins: - "@user2:{{ matrix_domain }}" ``` + ## Access token -You are required to specify an access token for Dimension to work. -To get an access token, follow these steps: + +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. +To get an access token for the Dimension user, follow these steps: 1. In a private browsing session (incognito window), open Riot. -2. It's preferable to use a dedicated user for the access token, so create and log in with that user's username and password. -3. Set the display name and avatar, if required. -4. In the settings page choose "Help & About", scroll down to the bottom and click `Access Token: `. -5. Copy the highlighted text to your configuration. -6. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work. +2. Log in with the `dimension` user and its password. +1. Set the display name and avatar, if required. +2. In the settings page choose "Help & About", scroll down to the bottom and click `Access Token: `. +3. Copy the highlighted text to your configuration. +4. Close the private browsing session. **Do not log out**. Logging out will invalidate the token, making it not work. **Access tokens are sensitive information. Do not include them in any bug reports, messages, or logs. Do not share the access token with anyone.** @@ -47,18 +56,23 @@ 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). + +## Installation + After these variables have been set, please run the following command to re-run setup and to restart Dimension: ``` ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start ``` + ## Jitsi domain By default Dimension will use [jitsi.riot.im](https://jitsi.riot.im/) as the `conferenceDomain` of [Jitsi](https://jitsi.org/) audio/video conference widgets. For users running [a self-hosted Jitsi instance](./configuring-playbook-jitsi.md), you will likely want the widget to use your own Jitsi instance. Currently there is no way to configure this via the playbook, see [this issue](https://github.com/turt2live/matrix-dimension/issues/345) for details. In the interim until the above limitation is resolved, an admin user needs to configure the domain via the admin ui once dimension is running. In riot-web, go to *Manage Integrations* → *Settings* → *Widgets* → *Jitsi Conference Settings* and set *Jitsi Domain* and *Jitsi Script URL* appropriately. + ## Additional features To use a more custom configuration, you can define a `matrix_dimension_configuration_extension_yaml` string variable and put your configuration in it.