{"id":13783628,"url":"https://github.com/matrix-org/matrix-bifrost","last_synced_at":"2025-04-30T03:49:50.563Z","repository":{"id":34611958,"uuid":"153536091","full_name":"matrix-org/matrix-bifrost","owner":"matrix-org","description":"General purpose bridging with a variety of backends including libpurple and xmpp.js","archived":false,"fork":false,"pushed_at":"2024-09-06T09:23:26.000Z","size":3277,"stargazers_count":169,"open_issues_count":158,"forks_count":33,"subscribers_count":20,"default_branch":"develop","last_synced_at":"2025-04-30T03:49:40.727Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/matrix-org.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-10-17T23:25:38.000Z","updated_at":"2025-04-21T13:44:43.000Z","dependencies_parsed_at":"2024-01-18T16:23:12.885Z","dependency_job_id":"82441c61-77bc-4eda-9c48-3b04f4436825","html_url":"https://github.com/matrix-org/matrix-bifrost","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-bifrost","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-bifrost/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-bifrost/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/matrix-org%2Fmatrix-bifrost/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/matrix-org","download_url":"https://codeload.github.com/matrix-org/matrix-bifrost/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251638760,"owners_count":21619663,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-03T19:00:26.926Z","updated_at":"2025-04-30T03:49:50.546Z","avatar_url":"https://github.com/matrix-org.png","language":"TypeScript","funding_links":[],"categories":["Bridges"],"sub_categories":["libpurple"],"readme":"# matrix-bifröst\n\n[![#bifrost:half-shot.uk](https://img.shields.io/matrix/bifrost:half-shot.uk?server_fqdn=matrix.org\u0026label=%23bifrost:half-shot.uk\u0026logo=matrix)](https://matrix.to/#/#bifrost:half-shot.uk)\n\nGeneral purpose puppeting bridges using libpurple and other backends.\n\nThis bridge is in very active development currently and intended mainly for experimentation and evaluation purposes.\n\nThis has been tested to work on `Node.JS v10` and `Synapse 0.34.0`.\n\n## Helping out\n\nIf you wish to file an issue or create a PR, **please read [CONTRIBUTING.md](./CONTRIBUTING.md) first.\n\n**NOTE: You must read this README carefully as simply installing required dependencies may NOT be enough for some backends**\n\n## Backends\n\nThis bridge features multiple backends for spinning up bridges on different types of network.\nThe following are supported:\n* `xmpp.js`\n    Designed to bridge to XMPP networks directly, without purple. Good for setups requiring an extremely scalable XMPP bridge. Uses XMPP components.\n* `node-purple`\n    Uses libpurple to bridge to a number of networks supported by libpurple2. Good for simple bridges for a small number of users, or for bridging to less available protocols.\n    `node-purple` is an optional dependency, which is installed by default. We currently don't publish prebuilt packages for it, so you will need to install buildtime dependencies\n    listed [on the README](https://github.com/matrix-org/node-purple).\n\n## Docker\n\nBoth backends are supported in Docker. You can go straight ahead and use the provided Dockerfile\nto build the bridge. You can build the docker image with `docker build -t bifrost:latest` and then\nrun the image with: `docker run -v /your/path/to/data:/data bifrost:latest -p 5000:9555`.\n\nAn image is available on [Dockerhub](https://hub.docker.com/r/matrixdotorg/matrix-bifrost).\n\n### Things to note\n\n- Make sure you store your `config.yaml`, `registration.yaml` inside /data.\n- You should configure your `config.yaml`'s `userStoreFile` and `roomStoreFile` to point to files inside `/data`\n- The intenal port for the bridge is `5000`, you should map this to an external port in docker.\n- Be careful not to leave any config options pointing to `127.0.0.1` / `localhost` as they will not resolve inside docker.\n - The exception to this rule is `bridge.domain`, which MUST be your homeserver's URL.\n\n## Installing (non-docker)\n\n### Dependencies\n\nSimply run `yarn install` as normal. Dependencies for `node-purple` can in it's [README](https://github.com/matrix-org/node-purple#node-purple)\n\n### Installing \u0026 Configuring\n\n**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.**\n\n```shell\nyarn install # Install dependencies\nyarn build # Build files\ncp config.sample.yaml config.yaml\n# ... Set the domain name, homeserver url, and then review the rest of the config\nsed -i  \"s/domain: \\\"localhost\\\"/domain: \\\"$YOUR_MATRIX_DOMAIN\\\"/g\" config.yaml\n```\n\nYou must also generate a registration file:\n\n```shell\nyarn genreg -- -u http://localhost:9555 # Set listener url here.\n```\n\nThis file should be accessible by your **homeserver**, which will use this file to get the correct url and tokens to push events to.\n\nFor Synapse, this can be done by:\n\n* Editing `app_service_config_files` in `homeserver.yaml` to include the full path of your registration file generated above.\n\n```yaml\napp_service_config_files: \n    - \".../bifrost-registration.yaml\"\n```\n\n* Restart synapse, if it is running (`synctl restart`)\n\n\n### XMPP bridge using the xmpp.js backend\n\nAfter completing all the above, you should do the following:\n* Set the `purple.backend` in `config.yaml` to `xmpp.js`\n* Possibly change the registration file alias and user regexes\n  to be `_xmpp_` instead of `_purple_`. Make sure to replicate those\n  changes in `config.yaml`\n* Setup your XMPP server to support a new component.\n* Setup the `purple.backendOpts` options for the new component.\n* Setup autoregistration and portals in `config.yaml`.\n\n### Starting\n\nThe `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.\n\nIf you are not using the `node-purple` backend, you can just start the service with:\n\n```shell\nyarn start -- -p 9555\n```\n\n## Help\n\n### Binding purple accounts to a Matrix User\n\nThe bridge won't do much unless it has accounts to bind. Due to the infancy of the bridge, we still use `~/.purple/accounts.xml`\nfor the location of all the accounts. Our advice is to create the accounts you want to use on your local machine with Pidgin, and\nthen copy the `accounts.xml` file to the bridge (where you should be copying the file to `/$BRIDGE_USER/.purple/accounts.xml`).\n\nOnce you have started the bridge, you can instruct it to bind by starting a conversation with the bridge user and\nsending `accounts add-existing $PROTOCOL $USERNAME` where the protocol and username are given in the `accounts.xml` file.\n\nYou should also run `accounts enable $PROTOCOL $USERNAME` to enable the account for the bridge, and then it should connect automatically.\n\n### My bridge crashed with a segfault\n\nThe `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\nif certain purple plugins cause more crashes, or if anything in particular lead up to it.\n## Testing\n\nRunning the tests is as simple as doing `yarn test`\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-bifrost","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatrix-org%2Fmatrix-bifrost","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatrix-org%2Fmatrix-bifrost/lists"}