finallycoffee/matrix-docker-ansible-deploy
finallycoffee/matrix-docker-ansible-deploy
5
1
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Make it clearer that Dimension requires a dedicated user

Browse Source
This commit is contained in:
Slavi Pantaleev 2020-05-06 10:29:43 +03:00
parent c1c8b8e62c
commit 884df93be1
1 changed files with 21 additions and 7 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

28
docs/configuring-playbook-dimension.md
View File

@ -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* &rightarrow; *Settings* &rightarrow; *Widgets* &rightarrow; *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.