matrix-org / matrix-org/matrix.org

We could use a guide on how to install and use bridges on Synapse

Open
#256 8 comments 7 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

potential guide
Dominant language
JavaScript
Stars
616
Forks
463
Avg merge
2d 3h
Merged PRs (30d)
19

Description

There's not a lot of information out there on how to actually set up a bridge (or appservice) on a homeserver. Although the process isn't terribly difficult, it can be a confusing task for people who don't have a full grasp on the components of Matrix.

The rough process is:
1. Follow the bridge instructions to get a "registration file" (the guide should have information as to what this is, also every bridge is different here)
2. Put the registration file next to your homeserver.yaml file
3. Add the registration file to the homeserver.yaml's appservice config section
4. **Restart synapse** (the step people forget)
5. Follow the bridge instructions to run the thing
6. Hope for the best

There's some additional complexity in there as well, such as when people want to run the bridge on a different host from synapse, or when they are using Docker. Ideally the guide would explain the importance of the `url` in the registration process and how it impacts the deployment process.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the existing bridge instructions and the homeserver.yaml appservice configuration, including the registration file and its url. The guide should cover the listed setup steps, restarting Synapse, bridges on a separate host, and Docker deployments, with enough context to explain the deployment choices.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker
Domain
documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
42/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.