Home

Awesome

matrix-bifröst

#bifrost:half-shot.uk

General purpose puppeting bridges using libpurple and other backends.

This bridge is in very active development currently and intended mainly for experimentation and evaluation purposes.

This has been tested to work on Node.JS v10 and Synapse 0.34.0.

Helping out

If you wish to file an issue or create a PR, **please read CONTRIBUTING.md first.

NOTE: You must read this README carefully as simply installing required dependencies may NOT be enough for some backends

Backends

This bridge features multiple backends for spinning up bridges on different types of network. The following are supported:

Docker

Both backends are supported in Docker. You can go straight ahead and use the provided Dockerfile to build the bridge. You can build the docker image with docker build -t bifrost:latest and then run the image with: docker run -v /your/path/to/data:/data bifrost:latest -p 5000:9555.

An image is available on Dockerhub.

Things to note

Installing (non-docker)

Dependencies

Simply run yarn install as normal. Dependencies for node-purple can in it's README

Installing & Configuring

NOTE: You must carefully read the config.sample.yaml and use the bits appropriate for you. Do NOT copy and paste it verbatim as it won't work.

yarn install # Install dependencies
yarn build # Build files
cp config.sample.yaml config.yaml
# ... Set the domain name, homeserver url, and then review the rest of the config
sed -i  "s/domain: \"localhost\"/domain: \"$YOUR_MATRIX_DOMAIN\"/g" config.yaml

You must also generate a registration file:

yarn genreg -- -u http://localhost:9555 # Set listener url here.

This file should be accessible by your homeserver, which will use this file to get the correct url and tokens to push events to.

For Synapse, this can be done by:

app_service_config_files: 
    - ".../bifrost-registration.yaml"

XMPP bridge using the xmpp.js backend

After completing all the above, you should do the following:

Starting

The start.sh script will auto preload the build libpurple library and offers a better experience than the system libraries in most cases. Pleas remember to modify the port in the script if you are using a different port.

If you are not using the node-purple backend, you can just start the service with:

yarn start -- -p 9555

Help

Binding purple accounts to a Matrix User

The bridge won't do much unless it has accounts to bind. Due to the infancy of the bridge, we still use ~/.purple/accounts.xml for the location of all the accounts. Our advice is to create the accounts you want to use on your local machine with Pidgin, and then copy the accounts.xml file to the bridge (where you should be copying the file to /$BRIDGE_USER/.purple/accounts.xml).

Once you have started the bridge, you can instruct it to bind by starting a conversation with the bridge user and sending accounts add-existing $PROTOCOL $USERNAME where the protocol and username are given in the accounts.xml file.

You should also run accounts enable $PROTOCOL $USERNAME to enable the account for the bridge, and then it should connect automatically.

My bridge crashed with a segfault

The node-purple rewrite is still not quite bugfree and we are working hard to iron out the kinks in it. We ask that you report if certain purple plugins cause more crashes, or if anything in particular lead up to it.

Testing

Running the tests is as simple as doing yarn test