Matrix-Mirrors/matrix-dimension
1
0
Fork 0
mirror of https://github.com/turt2live/matrix-dimension.git synced 2024-10-01 01:05:53 -04:00
Code Issues Packages Projects Releases Wiki Activity

Add docs for installing, troubleshooting, and non-federated environments

Browse Source 
Fixes https://github.com/turt2live/matrix-dimension/issues/248
Fixes https://github.com/turt2live/matrix-dimension/issues/160
Fixes https://github.com/turt2live/matrix-dimension/issues/258
This commit is contained in:
Travis Ralston 2019-03-27 20:52:07 -06:00
parent 0c0429df46
commit 80f4a8053e
3 changed files with 208 additions and 83 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

111
README.md
View File

@ -2,97 +2,34 @@
[![TravisCI badge](https://travis-ci.org/turt2live/matrix-dimension.svg?branch=master)](https://travis-ci.org/turt2live/matrix-dimension)
[![#dimension:t2bot.io](https://img.shields.io/badge/matrix-%23dimension:t2bot.io-brightgreen.svg)](https://matrix.to/#/#dimension:t2bot.io)
An open source integrations manager for matrix clients, like Riot.
An open source integrations manager for matrix clients, like Riot. For help and support, please visit
us in [#dimension:t2bot.io](https://matrix.to/#/#dimension:t2bot.io) on Matrix.
# Configuring Riot to use Dimension
# Installing Dimension / Running your own
Change the values in Riot's `config.json` as shown below. If you do not have a `config.json`, copy the `config.sample.json` from Riot.
```
"integrations_ui_url": "https://dimension.t2bot.io/riot",
"integrations_rest_url": "https://dimension.t2bot.io/api/v1/scalar",
"integrations_widgets_urls": ["https://dimension.t2bot.io/widgets"],
"integrations_jitsi_widget_url": "https://dimension.t2bot.io/widgets/jitsi",
```
The remaining settings should be tailored for your Riot deployment. If you're self-hosting Dimension, replace "dimension.t2bot.io" with your Dimension URL.
# Running your own
### Docker
To get started quickly, run the following command or build the Docker image:
```bash
docker run -p 8184:8184 -v /path/to/dimension/store:/data turt2live/matrix-dimension
```
In the `/path/to/dimension/store` make sure there is a file named `config.yaml`. This will be the configuration that Dimension uses.
### Compiling it yourself
Prerequisites:
* [NodeJS](https://nodejs.org/en/download/) 8
* npm 5 or higher (`npm install -g npm@latest`)
* A webserver running Riot or another supported client
```bash
# Download dimension
git clone https://github.com/turt2live/matrix-dimension.git
cd matrix-dimension
# Edit the configuration to your specifications.
# Be sure to add yourself as an admin!
cp config/default.yaml config/production.yaml
nano config/production.yaml
# Install dependencies
npm install
# Run
NODE_ENV=production npm run start:app
```
### Setting up Dimension
If you didn't change the port, Dimension should now be running on port 8184. It's best to set up your environment so that Dimension runs on a dedicated subdomain that *is not* the same as your Riot domain. This is to help keep Riot and Dimension safe and secure.
In your Riot `config.json`, set the integration manager to be your Dimension URL. Replace `dimension.t2bot.io` in the example above (under "Configuring Riot to use Dimension") with your Dimension URLs.
After Riot has been configured to use Dimension, refresh Riot and click the "Integrations" button in the top right of the room. It should be an icon that looks like this:
![3x3 square](https://t2bot.io/_matrix/media/r0/download/t2l.io/gOgboDPEMfiYOQryYwvvHkFz)
That button should open Dimension. If you've configured everything correctly, you'll see a gear icon in the top right of the window - click this to start editing your integrations.
### Running Dimension behind nginx
1. Follow the steps outlined above.
2. Set the host for Dimension to listen on to `localhost` or `127.0.0.1`
3. Restart Dimension (`CTRL+C` and run `NODE_ENV=production npm run start:app` again)
4. Set up the following reverse proxy information as applicable
```
location / {
proxy_set_header X-Forwarded-For $remote_addr;
proxy_pass http://localhost:8184;
}
```
Be sure to also configure any SSL offloading.
See [docs/installing.md](./docs/installing.md) for more information on running Dimension.
### "Could not contact integrations server" error
1. **Check that federation is enabled and working on your homeserver.** Even in a private, or non-federated environment, the federation API still needs to be accessible. If federation is a major concern, limit the servers that can use the API by IP or install Dimension on the same server as your homeserver, only exposing federation to localhost.
2. **Check your SRV records.** If you are using SRV records to point to your federation port, make sure that the hostname and port are correct, and that HTTPS is listening on that port. Dimension will use the first record it sees and will only communicate over HTTPS.
3. **Verify the homeserver information in your configuration.** The name, access token, and client/server API URL all need to be set to point towards your homeserver. It may also be necessary to set the federation URL if you're running a private server.
# Development
For more information about working on Dimension, see DEVELOPMENT.md.
1. **Check that federation is enabled and working on your homeserver.** If you're not intentionally
running Dimension in a non-federated environment, make sure that your homeserver is configured
correctly. If you are running in a non-federated environment, consult [docs/unfederated.md](./docs/unfederated.md).
2. **Check your SRV records and .well-known delegation.** If you are using SRV records to point to your
federation port, make sure that the hostname and port are correct, and that HTTPS is listening on that
port. Dimension will use the first record it sees and will only communicate over HTTPS. If you're using
.well-known delegation for federation, double check that is set up correctly.
3. **Verify the homeserver information in your configuration.** The name, access token, and client/
server API URL all need to be set to point towards your homeserver. It may also be necessary to set the
federation URL if you're running a private server.
4. **Run the troubleshooter.** If you're on Riot 1.1.0 or higher, type `/addwidget https://dimension.t2bot.io/widgets/manager-test`
in a private room then click the button.
# Do I need an integrations manager?
Integration managers aim to ease a user's interaction with the various services a homeserver may provide. Often times the integrations manager provided by Riot.im, named Modular, is more than suitable. However, there are a few cases where running your own makes more sense:
Integration managers aim to ease a user's interaction with the various services a homeserver may
provide. Often times the integrations manager provided by Riot.im, named Modular, is more than suitable.
However, there are a few cases where running your own makes more sense:
* Wanting to self-host all aspects of your services (client, homeserver, and integrations)
* Wanting to advertise custom bots specific to your homeserver
@ -100,11 +37,19 @@ Integration managers aim to ease a user's interaction with the various services
# How do integration managers work?
Integration managers sit between your users and your integrations (bots, bridges, etc). It helps guide users through the configuration of your integrations for their rooms. The integrations manager can only manage integrations it is configured for. For example, Modular can only provide configuration for the bridges and bots running on matrix.org, while Dimension can provide configuration for your own bots and bridges.
Integration managers sit between your users and your integrations (bots, bridges, etc). It helps guide
users through the configuration of your integrations for their rooms. The integrations manager can only
manage integrations it is configured for. For example, Modular can only provide configuration for the
bridges and bots running on matrix.org, while Dimension can provide configuration for your own bots and
bridges.
The infrastructure diagram looks something like this:
![infrastructure](https://t2bot.io/_matrix/media/r0/download/t2l.io/3bb5674d85ee22c070e36be0d9582b4d)
# Development
For more information about working on Dimension, see DEVELOPMENT.md.
# License
For information about Dimension's license, please see the LICENSE file included in this repository.

161
docs/installing.md Normal file
View File

@ -0,0 +1,161 @@
## Installing Dimension
**Note**: Dimension is currently only capable of running with Riot Web or Desktop. The iOS and Android
apps are not directly supported without compiling your own versions. In future, this should be handled
by [an integration manager specification](https://github.com/turt2live/matrix-dimension/issues/262).
There are several options for installing Dimension. The easiest is dependent on how you have Riot
and your homeserver set up. If you're using [matrix-docker-ansible-deploy](https://github.com/spantaleev/matrix-docker-ansible-deploy),
there are already options for configuring Dimension.
### Step 0: Requirements
You will need a functioning homeserver (such as [Synapse](https://github.com/matrix-org/synapse)) and
a client to access Dimension with. Currently, that means using [Riot Web or Desktop](https://riot.im).
Additionally, you will need to be able to host Dimension on a dedicated domain. If your homeserver
is set up for example.org, we recommend using dimension.example.org for Dimension.
Finally, this guide assumes you are running nginx as a webserver for Riot, your homeserver, and
Dimension. A basic configuration before setting up Dimension would be:
```conf
server {
# Simple configuration for Synapse. Consult the Synapse documentation for however you would
# like to run your homeserver.
server_name example.org;
listen 443 ssl;
listen [::]:443 ssl;
location /_matrix {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://localhost:8008;
}
}
server {
# Simple configuration for serving Riot
server_name chat.example.org;
listen 443 ssl;
listen [::]:443 ssl;
root /var/www/html;
index index.html;
location / {
try_files $uri $uri/ =404.html;
}
}
```
The SSL options are not shown. Using [Let's Encrypt with nginx](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-ubuntu-18-04)
is fairly straightforward, however.
**Note**: If you're running Dimension in an unfederated environment, you'll have some additional setup
to do. See [unfederated.md](./unfederated.md) for more information.
### Step 1: Picking between Docker and building Dimension yourself
Docker images are provided as `turt2live/matrix-dimension` and require fewer resources than building
it yourself.
If you're using Docker, create a directory at `/etc/dimension` (or wherever you'd like - just remember
where it is!).
To build Dimension yourself, you'll need Node 10, npm 6, and 2-4gb of RAM. The following steps are enough
to get you started:
```bash
# Download dimension
git clone https://github.com/turt2live/matrix-dimension.git
cd matrix-dimension
# Install dependencies
npm install
# Build it
npm run build
```
### Step 2: Configuring Dimension
**Docker**: Using [the default config](https://github.com/turt2live/matrix-dimension/blob/master/config/default.yaml)
as an example, create a file at `/etc/dimension/config.yaml`.
**Building**: Copy `config/default.yaml` to `config/production.yaml`
After creating the file, open it in an editor like `nano` and start filling in the details. Don't forget
to add your user ID as an admin in the configuration - this is important later!
If you're using Docker, leave the `web` `port` and `address` as-is. Additionally, make sure to configure
the `database` section to look like this:
```yaml
database:
file: "/data/dimension.db"
botData: "/data/bot.json"
```
### Step 3: Running Dimension
**Docker**:
```bash
docker run -d --name dimension -p 127.0.0.1:8184:8184 -v /etc/dimension:/data turt2live/matrix-dimension
```
**Building**:
```bash
NODE_ENV=production npm run start:app
```
If all went well, Dimension should now be running - there's still a bit more configuration to
go though.
### Step 4: Configuring nginx
Create a new server definition for your nginx server:
```conf
server {
server_name dimension.example.org;
listen 443 ssl;
listen [::]:443 ssl;
root /var/www/html;
index index.html;
location / {
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_pass http://localhost:8184;
}
}
```
Reload or restart nginx after creating the configuration.
### Step 5: Final steps
If everything went according to plan, you should be able to visit `https://dimension.example.org`
and see instructions for configuring Riot. If you don't, your configuration isn't working as
intended - double check that all the configuration is set up and visit [#dimension:t2bot.io](https://matrix.to/#/#dimension:t2bot.io)
for further help.
After configuring Riot, click the integrations button (4 squares in the top right of any room) and
then click the gear icon. If you don't see a gear icon, you're not an admin in the config. This is
where you'll configure different integrations as Dimension doesn't ship with anything enabled by
default - click around and start enabling things.
### Step 6: Updating and restarting Dimension
**Docker**:
```bash
docker pull turt2live/matrix-dimension
docker restart dimension
```
**Building**:
```bash
# Kill the running Dimension process, then...
git pull
npm run build
NODE_ENV=production npm run start:app
```

19
docs/unfederated.md Normal file
View File

@ -0,0 +1,19 @@
## Running Dimension in a private/non-federated environment
Using the Synapse documentation, start building your homeserver's configuration. Where the default
configuration enables a `federation` listener, use `openid` instead. For example, your `listeners`
may look something like this:
```yaml
listeners:
- port: 8008
bind_addresses: ['::1', '127.0.0.1']
type: http
x_forwarded: true
resources:
- names: [client, openid]
compress: false
```
Afterwards, either configure your homeserver as though federation was enabled (create SRV records, for
example) or make use of Dimension's `federationUrl` configuration option to point directly at the
listener configured in Synapse.