Merge pull request #111 from NullIsNot0/master

Provide Dimension documentation

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
 

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.<your-domain>` |
+| CNAME | `dimension`             | -        | -      | -    | `matrix.<your-domain>` |
 | SRV   | `_matrix._tcp`          | 10       | 0      | 8448 | `matrix.<your-domain>` |
 | SRV   | `_matrix-identity._tcp` | 10       | 0      | 443  | `matrix.<your-domain>` |
 
@@ -40,6 +41,8 @@ As the table above illustrates, you need to create 2 subdomains (`matrix.<your-d
 The `riot.<your-domain>` 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.<your-domain>` DNS record.
 
+The `dimension.<your-domain>` 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.<your-domain>` DNS record.
+
 
 ## `_matrix._tcp` SRV record setup (temporary requirement)
 

docs/configuring-playbook-dimension.md

@@ -0,0 +1,53 @@
+# Setting up Dimension (optional)
+
+**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.<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/matrix.<your-domain>/vars.yml`):
+
+```yaml
+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/matrix.<your-domain>/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: <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.
+
+**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.<your-domain>/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).

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](configuring-playbook-dimension.md) (optional)

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)