asonix/matrix-dimension
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Update some documentation

Browse source
This commit is contained in:
Travis Ralston 2017-12-22 16:38:48 -07:00
parent 9a9bd2c5ac
commit d3ab2debbc
4 changed files with 94 additions and 197 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

51
DEVELOPMENT.md Normal file
View file

@ -0,0 +1,51 @@
# Dimension Development
Dimension is split into two layers: the frontend (web) and backend. The frontend is responsible for interacting with the client (Riot) directly and hands off any complex work to the backend for processing.
**For help and support related to Dimension development, please visit:**
[![#dimension:t2bot.io](https://img.shields.io/badge/matrix-%23dimension:t2bot.io-brightgreen.svg)](https://matrix.to/#/#dimension:t2bot.io)
## Running
The prerequisites for development are the same as running Dimension in a production environment.
```
# Edit the configuration to your specifications.
# Be sure to add yourself as an admin!
cp config/default.yaml config/development.yaml
nano config/development.yaml
# Run the webserver (it watches for changes)
npm run start:dev
# Run the backend (does not watch for changes)
npm run build:app && node build/app/index.js
```
## General architecture
Integrations are defined in the database for administrators to enable, disable, and configure as they please. They are added using migrations (or in some cases, manually by the administrators) and should always be added as "disabled" by default.
The frontend has two sections: the admin and non-admin sections. The admin section is used by authorized users to configure the various integrations, or parts of integrations. The non-admin section is used by everyone else to add the integrations to their rooms.
The frontend automatically routes edit pages in both the admin and non-admin sections to the appropriate routes. It does this by using a combination of the `category` and `type` of the integrations. For example, a `widget` with the type `jitsi` will be redirected to the `/riot-app/widget/jitsi` route for editing. Both the admin and non-admin routes need to be declared in the `app.routing.ts` class. After that, it is best to copy/paste a similar widget component and edit it to your needs.
The backend is slightly more complicated, where particular integrations may have their own API defined depending on the complexity involved. For example, all bridges have their own admin and non-admin API to configure the various parts. The required changes to the backend are described in the later sections of this document.
## Adding new widgets
TODO
## Adding new go-neb services
TODO
## Adding new bridges
TODO
## Adding new bots
TODO
*note to self: are simple bots even a thing anymore?*

64
INTEGRATIONS.md
View file

@ -1,64 +0,0 @@
# Integrations in Dimension
Integrations take the form of bots, bridges, widgets, and other tools that enhance user experience in particular rooms. This document goes through the various setup procedures for the different types of integrations.
Several integrations already have configuration files in the `config/integrations` folder. Each default configuration has additional information as to how to configure it. Some integrations are disabled by default and can be found in the `config/integrations/samples` folder.
## Simple Bots
A simple bot is a bot that requires no configuration by users. It simply exists in the room and provides some minor functionality. Examples of this are the Giphy, Guggy, and Wikipedia bots.
1. Create a new configuration file in `config/integrations` for the bot.
2. Put the following contents in the configuration file:
```
# This is required. Leave it as "bot" for this configuration.
type: "bot"
# We should probably make sure it is enabled too ;)
enabled: true
# This is a unique key to identify your bot. For example, "giphy".
integrationType: "YOUR_BOT_NAME"
# The matrix user ID for the bot. This is likely to be on your server.
userId: "@userID:server.com"
# The name to use in the UI for Dimension. Try to keep this short.
name: "Some Friendly Bot"
# A brief description of the bot. These are best kept under 60 characters.
about: "Use `!some command` to interact with the bot"
# A logo for your bot. We'll upload this in a moment.
avatar: "img/avatars/YOUR_BOT_NAME.png"
# This is the actual bot configuration so Dimension can control some aspects of the bot's behaviour (leaving rooms, etc).
hosted:
# The URL to the client/server API. This is the "Homeserver URL" in Riot.
homeserverUrl: "https://matrix.org"
# The access token for the bot. For information on how to get this, visit https://t2bot.io/docs/access_tokens
accessToken: "your_matrix_access_token_here"
```
3. Upload/copy the logo for the bot to the `img/avatars` folder, as mentioned above.
4. Restart Dimension
Your bot should now be in Dimension!
## Complex Bots
Complex bots are the bots that require configuration within Dimension in order to work. Examples include the Github bot or RSS bot. Currently these bots are not as easy to set up in Dimension as they could be, and require a developer to write code for Dimension to understand the requirements.
To request a particular complex bot to be supported, please open a new issue on Github.
## Bridges
Bridges allow people in matrix to talk to people not in matrix, and vice-versa. Like complex bots, bridges require additional code in Dimension in order to be supported.
To request a particular bridge to be supported, please open a new issue on Github.
## Widgets
Widgets are web applications that can be embedded in a room for users to interact with. Like bridges and complex bots, widgets require additional code in Dimension to be supported.
To request a particular widget, please open a new issue on Github.

90
README.md
View file

@ -1,16 +1,9 @@
# Dimension
![dimension](https://t2bot.io/_matrix/media/v1/download/t2l.io/CceFARjXLjomNdUbKjXbGrDF)
[![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 alternative integrations manager for [Riot](https://riot.im). Join us on matrix: [#dimension:t2l.io](https://matrix.to/#/#dimension:t2l.io)
![screenshot](https://t2bot.io/_matrix/media/v1/download/t2l.io/kWDyaWXqdsjOJgGYAMMRgGiE)
# ⚠️ Dimension is in Alpha ⚠️
Dimension supports some bridges and bots, however using Dimension in a production scenario is not recommended. Dimension uses features available in recent builds of Riot and may not work on older versions.
There are plans on the matrix.org front to better support integration managers. Those changes may require an updated homeserver and Riot when made available.
An alternative integrations manager for [Riot.im](https://riot.im).
# Configuring Riot to use Dimension
@ -22,29 +15,46 @@ Change the values in Riot's `config.json` as shown below. If you do not have a `
"integrations_widgets_urls": ["https://dimension.t2bot.io/widgets"],
```
The remaining settings should be tailored for your Riot deployment.
# Building
To create a production build of Dimension, run `npm run build`. For development environments, see the Development section below.
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
1. Run `npm run build`
2. Copy `config/default.yaml` to `config/production.yaml` and edit `config/production.yaml`
3. Edit any integration settings in `config/integrations`
4. Run Dimension with `NODE_ENV=production node app.js`
Prerequisites:
* [NodeJS](https://nodejs.org/en/download/) 8 or higher
* npm 5 or higher (`npm install -g npm@latest`)
* TypeScript 2.6 or higher (`npm install -g typescript`)
* A webserver running Riot
Dimension is now available on the port/host you configured.
```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
# Run
NODE_ENV=production npm run start:app
```
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/v1/thumbnail/t2l.io/gOgboDPEMfiYOQryYwvvHkFz?width=800&height=600)
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. Run `npm run build`
2. Copy `config/default.yaml` to `config/production.yaml` and edit `config/production.yaml`
3. Edit any integration settings in `config/integrations`
4. Set the host for Dimension to listen on to `localhost` or `127.0.0.1`
5. Run Dimension with `NODE_ENV=production node app.js`
6. Set up the following reverse proxy information as applicable
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;
@ -53,11 +63,15 @@ Dimension is now available on the port/host you configured.
```
Be sure to also configure any SSL offloading.
### "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. **Log out of Riot and log back in.** When switching from the default integrations manager (Scalar) to Dimension the authentication tokens can change. Logging out and back in will reset this token, allowing Dimension to work. More advanced users can delete the "mx_scalar_token" localstorage key.
# Development
1. Copy `config/default.yaml` to `config/development.yaml` and make any edits
2. Run Dimension with `NODE_ENV=development node app.js`
3. Run the web app with `npm run dev`
For information on how to run Dimension in a local environment, and for information about how the project is structured, see DEVELOPMENT.md
# Do I need an integrations manager?
@ -84,24 +98,6 @@ The infrastructure diagram looks something like this:
+-----------+ +-------------+
```
# Common Problems / Setup Questions
Dimension uses unstable and undocumented parts of Riot and can sometimes be a bit difficult to set up. If you're running into issues, check the solutions below. If you're still having issues, come by [#dimension:t2bot.io](https://matrix.to/#/#dimension:t2bot.io) and we can help you out.
## Setting up integrations (including custom)
The INTEGRATIONS.md file in this repository explains how to add custom integrations. For assistance, please visit [#dimension:t2bot.io](https://matrix.to/#/#dimension:t2bot.io)
## "Could not contact integrations server"
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. **Log out of Riot and log back in.** When switching from the default integrations manager (Scalar) to Dimension the authentication tokens can change. Logging out and back in will reset this token, allowing Dimension to work. More advanced users can delete the "mx_scalar_token" localstorage key.
## Turning off matrix.org/Scalar dependency
To completely disconnect Dimension from using the matrix.org bots and bridges, remove the `vector` upstream from your config. This will force anything using the upstream (matrix.org bots and bridges) to not load.
# License
For information about Dimension's license, please see the LICENSE file included in this repository.

86
docs/development/adding_widgets.md
View file

@ -1,86 +0,0 @@
# Adding new widgets to Dimension
Widgets are small/simple applications that can be loaded via iframes in a Riot.im room. Dimension supports "wrapped widgets" where each widget URL is held in some kind of wrapper to ensure it can make everything work for that widget. For example, Jitsi widgets are wrapped so that the Jitsi elements can be set up.
To add a new widget to Dimension:
1. Copy and existing widget's configuration file from `config/integrations` and update it accordingly. The bare minimum is:
```yaml
# These two options should never change
type: "widget"
enabled: true
integrationType: "mywidget" # This is the widget type
name: "My Widget" # The human-readable name for the widget
about: "This is a very brief description of the widget"
avatar: "img/avatars/mywidget.png" # Should be a 120x120 PNG image.
# Located at `web/public/img/avatars/mywidget.png`
```
2. In `web/app/shared/models/widget.ts` add a constant for your widget. In this example, it would be:
```typescript
export const WIDGET_MY_WIDGET = ["mywidget"];
```
3. Add a new component to configure your widget under `web/app/configs/widget` (this is best done by copy/pasting another similar widget's component and renaming the files and class name).
4. Register the component in `web/app/shared/integration.service.ts` under the `supportedIntegrationsMap` like so:
```typescript
private static supportedIntegrationsMap = {
"widget": {
"mywidget": {
component: MyWidgetConfigComponent,
types: WIDGET_MY_WIDGET,
},
},
};
```
5. Start building out the widget configuration component.
## Widget configuration component methods
Most widgets should be able to specify their entire behaviour through use of the constructor, however some do require some additional hooks to operate correctly. For example, widgets being imported from older versions of Dimension or other integration managers may have to be massaged into compatible widgets.
All widgets rely on the `data` property bag to store state information, such as a channel name or conference name. This information is automatically persisted as part of the widget. Whenever you are interacting with a widget in the context of editing or creating it be sure to use the properties under `dimension` on the widget, otherwise your changes may be overwritten.
Here's a few examples of how to use the hooks supplied by the widget configuration component. For more information on all of the hooks available, please see the bottom of `web/app/configs/widget/widget.component.ts`.
#### Expanding the widget's data prior to creation
This is common for when a widget wants to create a new widget based on a channel name (for example).
```typescript
protected onNewWidgetPrepared() {
this.newWidget.dimension.newData.channelName = "";
}
```
#### Modifying the widget URL (or other properties) before adding/saving
```typescript
// Make sure to call these methods instead of addWidget and saveWidget in the view!
public validateAndAddWidget() {
this.newWidget.dimension.newUrl = "https://somewhere.com";
this.addWidget();
}
public validateAndSaveWidget(widget: EditableWidget) {
widget.dimension.newUrl = "https://somewhere.com";
this.saveWidget(widget);
}
```
#### Converting widgets from other data sources (Scalar, older versions, etc)
```typescript
protected onWidgetsDiscovered() {
for (const widget of this.widgets) {
// Note the use of .data instead of .dimension here.
// This is because we're not editing or creating a widget - just preparing it.
if (widget.data.oldDataKey) {
widget.data.newDataKey = widget.data.oldDataKey;
}
}
}
```