From 1bff4893d97c1cdbc24dd7783f33b0d873729fcb Mon Sep 17 00:00:00 2001 From: Edgars Voroboks Date: Sun, 10 Mar 2019 10:12:31 +0200 Subject: [PATCH 1/2] 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 67c1373e..35b18ec2 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 cdb54090..de7f8487 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 00000000..78e41fbf --- /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 6285d4d1..5cc609c3 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) From 9f5215c95a018452ed1d5b20609a43c723c2acba Mon Sep 17 00:00:00 2001 From: Edgars Voroboks Date: Sun, 10 Mar 2019 13:17:56 +0200 Subject: [PATCH 2/2] Make some additions to Dimension documentation --- docs/configuring-dns.md | 2 +- docs/configuring-playbook-dimension.md | 15 ++++++++++----- docs/configuring-playbook.md | 2 +- docs/installing.md | 1 + 4 files changed, 13 insertions(+), 7 deletions(-) diff --git a/docs/configuring-dns.md b/docs/configuring-dns.md index de7f8487..c96a9206 100644 --- a/docs/configuring-dns.md +++ b/docs/configuring-dns.md @@ -41,7 +41,7 @@ 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. +The `dimension.` subdomain may be necessary, because this playbook could install the [Dimension integrations manager](http://dimension.t2bot.io/) for you. Dimension installation is disabled by default, because it's only possible to install it after the other Matrix services are working (see [Setting up Dimension](docs/configuring-playbook-dimension.md) later). If you do not wish to set up Dimension, 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 index 78e41fbf..e6ed4a76 100644 --- a/docs/configuring-playbook-dimension.md +++ b/docs/configuring-playbook-dimension.md @@ -1,15 +1,20 @@ # Setting up Dimension (optional) -Dimension integrations manager installation is disabled by default. You can enable it in your configuration file (`inventory/matrix./vars.yml`): +**Dimension can only be installed after Matrix services are installed and running.** +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 +For an Integration Manager like Dimension to work, your server needs to have federation enabled (`matrix_synapse_federation_enabled: true`). This is the default for this playbook, so unless you've explicitly disabled federation, you're okay. + +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/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. diff --git a/docs/configuring-playbook.md b/docs/configuring-playbook.md index 5cc609c3..3da733b2 100644 --- a/docs/configuring-playbook.md +++ b/docs/configuring-playbook.md @@ -55,4 +55,4 @@ When you're done with all the configuration you'd like to do, continue with [Ins - [Setting up Appservice Discord bridging](configuring-playbook-bridge-appservice-discord.md) (optional) -- [Setting up Dimension (optional)](configuring-playbook-dimension.md) (optional) +- [Setting up Dimension](configuring-playbook-dimension.md) (optional) diff --git a/docs/installing.md b/docs/installing.md index 38536f5a..90209e57 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -36,5 +36,6 @@ Now that the services are running, you might want to: - **finalize the installation process** (required for federation to work!) by [Configuring Service Discovery via .well-known](configuring-well-known.md) - or [create your first user account](registering-users.md) +- or [set up the Dimension Integrations Manager](configuring-playbook-dimension.md) - or [check if services work](maintenance-checking-services.md) - or learn how to [upgrade your services when new versions are released](maintenance-upgrading-services.md)