| @@ -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. | 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 | ## 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`. | 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. | 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 | ## 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`): | [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 | ```yaml | ||||
| @@ -17,6 +20,7 @@ matrix_dimension_enabled: true | |||||
| ## Define admin users | ## 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. | 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`): | Add this to your configuration file (`inventory/host_vars/matrix.<your-domain>/vars.yml`): | ||||
| @@ -26,16 +30,21 @@ matrix_dimension_admins: | |||||
| - "@user2:{{ matrix_domain }}" | - "@user2:{{ matrix_domain }}" | ||||
| ``` | ``` | ||||
| ## Access token | ## 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. | 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.** | **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). | 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: | 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 | ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start | ||||
| ``` | ``` | ||||
| ## Jitsi domain | ## 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. | 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. | 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 | ## 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. | To use a more custom configuration, you can define a `matrix_dimension_configuration_extension_yaml` string variable and put your configuration in it. | ||||