From 1bff4893d97c1cdbc24dd7783f33b0d873729fcb Mon Sep 17 00:00:00 2001 From: Edgars Voroboks Date: Sun, 10 Mar 2019 10:12:31 +0200 Subject: [PATCH] Provide Dimension documentation --- README.md | 4 +++ docs/configuring-dns.md | 3 ++ docs/configuring-playbook-dimension.md | 48 ++++++++++++++++++++++++++ docs/configuring-playbook.md | 2 ++ 4 files changed, 57 insertions(+) create mode 100644 docs/configuring-playbook-dimension.md diff --git a/README.md b/README.md index 67c1373ec..35b18ec23 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,8 @@ Using this playbook, you can get the following services configured on your serve - (optional) the [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) bridge for bridging your Matrix server to [Discord](https://discordapp.com/) +- (optional) [Dimension](https://github.com/turt2live/matrix-dimension), an open source integrations manager for matrix clients + Basically, this playbook aims to get you up-and-running with all the basic necessities around Matrix, without you having to do anything else. **Note**: the list above is exhaustive. It includes optional or even some advanced components that you will most likely not need. @@ -118,6 +120,8 @@ This playbook sets up your server using the following Docker images: - [tedomum/matrix-appservice-discord](https://hub.docker.com/r/halfshot/matrix-appservice-discord) - the [matrix-appservice-discord](https://github.com/Half-Shot/matrix-appservice-discord) bridge to [Discord](https://discordapp.com/) +- [turt2live/matrix-dimension](https://hub.docker.com/r/turt2live/matrix-dimension) - the [Dimension](https://dimension.t2bot.io/) integrations manager (optional) + ## Deficiencies diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md index cdb54090c..de7f8487a 100644 --- a/docs/configuring-dns.md +++ b/docs/configuring-dns.md @@ -26,6 +26,7 @@ It's a temporary requirement during the Synapse v0.99/v1.0 transition. | ----- | ----------------------- | -------- | ------ | ---- | ---------------------- | | A | `matrix` | - | - | - | `matrix-server-IP` | | CNAME | `riot` | - | - | - | `matrix.` | +| CNAME | `dimension` | - | - | - | `matrix.` | | SRV | `_matrix._tcp` | 10 | 0 | 8448 | `matrix.` | | SRV | `_matrix-identity._tcp` | 10 | 0 | 443 | `matrix.` | @@ -40,6 +41,8 @@ As the table above illustrates, you need to create 2 subdomains (`matrix.` subdomain is necessary, because this playbook installs the Riot web client for you. If you'd rather instruct the playbook not to install Riot (`matrix_riot_web_enabled: false` when [Configuring the playbook](configuring-playbook.md) later), feel free to skip the `riot.` DNS record. +The `dimension.` subdomain is necessary, because this playbook installs the Dimension integrations manager for you. Dimension installation is disabled by default and if you explicitly do not enable it's installation (`matrix_dimension_enabled: true` when [Configuring the playbook](configuring-playbook.md) later), feel free to skip the `dimension.` DNS record. + ## `_matrix._tcp` SRV record setup (temporary requirement) diff --git a/docs/configuring-playbook-dimension.md b/docs/configuring-playbook-dimension.md new file mode 100644 index 000000000..78e41fbf0 --- /dev/null +++ b/docs/configuring-playbook-dimension.md @@ -0,0 +1,48 @@ +# Setting up Dimension (optional) + +Dimension integrations manager installation is disabled by default. You can enable it in your configuration file (`inventory/matrix./vars.yml`): + +```yaml +matrix_dimension_enabled: true +``` +Your Matrix also needs federation enabled for Dimension to work, so if you have disabled it by setting `matrix_synapse_federation_enabled` to `false`, please remove or comment this variable in your configuration file. Or set it to: + +```yaml +matrix_synapse_federation_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/matrix./vars.yml`): + +```yaml +matrix_dimension_admins: ['@user1:domain.com', '@user2:domain.com'] +``` + +## Access token +You are required to specify an access token for Dimension to work. +To get an access token, follow these steps: + +1. In a private browsing session (incognito window), open Riot. +2. It's better to you use dedicated user for getting access token, so log in with this user's username and password. +3. Set the display name and avatar, if required. +4. In the settings page, 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. + +**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/matrix./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). + +## 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 learn more about how to do this, refer to the information about `matrix_dimension_configuration_extension_yaml` in the [default variables file](../roles/matrix-dimension/defaults/main.yml) of the Dimension component. + +You can find all configuration options on [GitHub page of Dimension project](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml). diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 6285d4d17..5cc609c34 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -54,3 +54,5 @@ When you're done with all the configuration you'd like to do, continue with [Ins - [Setting up Appservice IRC bridging](configuring-playbook-bridge-appservice-irc.md) (optional) - [Setting up Appservice Discord bridging](configuring-playbook-bridge-appservice-discord.md) (optional) + +- [Setting up Dimension (optional)](configuring-playbook-dimension.md) (optional)