Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/matrix-org/matrix-appservice-gitter

Matrix <-> Gitter bridge
https://github.com/matrix-org/matrix-appservice-gitter

Last synced: 26 days ago
JSON representation

Matrix <-> Gitter bridge

Awesome Lists containing this project

README

        

## Deprecation Notice
This bridge has been deprecated in favor of the [Native Glitter Bridge](https://www.matrix.org/docs/projects/bridge/native-gitter-bridge) that is automatically deployed for you.

Installation
------------

```sh
$ git clone ...
$ cd matrix-appservice-gitter
$ npm install
```

Setup
-----

1. Create a github user to act as the relay bot itself in gitter chanels.
Obtain the user's gitter API key by visiting
https://developer.gitter.im/apps

1. Create a new Matrix room to act as the administration control room. Note
its internal room ID.

1. Create a `gitter-config.yaml` file for global configuration. There is a
sample one to begin with in `config/gitter-config-sample.yaml` you may wish
to copy and edit as appropriate. This needs the following keys:

```yaml
gitter_api_key: "the API key obtained in step 1"

matrix_homeserver: "http URL pointing at the homeserver"

matrix_user_domain: "domain part of the homeserver's name. Used for
ghost username generation"

username_template: "template for virtual users, e.g. gitter_${USER}"

matrix_admin_room: "the ID of the room created in step 2"
```

1. Pick/decide on a spare local TCP port number to run the application service
on. This needs to be visible to the homeserver - take care to configure
firewalls correctly if that is on another machine to the bridge. The port
number will be noted as `$PORT` in the remaining instructions.

1. Generate the appservice registration file (if the application service runs
on the same server you can use localhost as `$URL`):

```sh
$ node index.js --generate-registration -f gitter-registration.yaml -u $URL:$PORT
```

1. Start the actual application service. You can use forever

```sh
$ forever start index.js --config gitter-config.yaml --port $PORT
```

or node

```sh
$ node index.js --config gitter-config.yaml --port $PORT
```

1. Copy the newly-generated `gitter-registration.yaml` file to the homeserver.
Add the registration file to your homeserver config (default `homeserver.yaml`):

```yaml
app_service_config_files:
- ...
- "/path/to/gitter-registration.yaml"
```

Don't forget - it has to be a YAML list of strings, not just a single string.

Restart your homeserver to have it reread the config file and establish a
connection to the bridge.

1. Invite the newly-created `@gitterbot:DOMAIN` user into the admin control
room created at step 2.

The bridge should now be running.

Provisioning
------------

The bridge is controlled by commands in the admin control room.

> link [matrix room ID] [gitter room name]

Creates a new link between the given matrix room ID
(example: `!abcdef:example.org`) and the gitter room name
(example: `gitterHQ/sandbox`) and joins the associated gitter room. The relay
user must be invited to the matrix room for this to become functional.

> unlink [matrix room ID or gitter room name]

Disconnects the link associated with the given room and leaves the
associated gitter room

Dynamic Portals
---------------

As well as the linked rooms created by administrator users on the console, it
is also possible to enable "dynamic portals", a feature in which the bridge
itself will lazily create linked rooms in response to alias lookup requests
within a given namespace.

1. Set the following extra configuration values in the main
`gitter-config.yaml` file:

```yaml
enable_portals: true

alias_template: "template for room aliases, e.g. gitter_${ROOM}"
```

1. Ensure that the appservice registration file requests an alias regexp
pattern that will match the alias template form, e.g.:

```yaml
...
namespaces:
aliases:
- exclusive: true
regex: '#gitter_.*'
```

If you've edited the registration file, don't forget to restart the
homeserver to have the new values applied.

You should now be able to dynamically create new portal rooms by directly
attempting to join room aliases matching this template. These rooms will
behave similarly to administrator-provisioned link rooms, except that because
the application service itself created the Matrix-side room, it retains full
operator control of the room.

For top-level gitter rooms like organisations, repositories and user rooms,
you can simply embed the name in the alias. For example, the top-level gitter
chat room relating to ``my-org-here`` would be found at:

> /join #gitter_my-org-here:localhost

To join a channel nested withn an organisation, repository or user account,
you'll need to encode the ``/`` character as ``=2F``. For example, the
``my-org-here/chat`` room would be found at:

> /join #gitter_my-org-here=2Fchat:localhost

Alternatively, if you wish to be able to create these portals only from the
admin console without letting all your users dynamically create their own, you
can leave the ``aliases`` list empty in the registration file, so that the
homeserver won't ask the application service to dynamically create them.
Instead, you can provision them directly by using the admin control room.

> mkportal [gitter room name]

Will create a new portal room for the given gitter room name and print its
alias. Once created, these rooms act the same as other dynamic portals.