| @@ -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.<your-domain>` 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.<your-domain>/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.<your-domain>/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: <click to reveal>`. | |||
| 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: <click to reveal>`. | |||
| 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. | |||