Bridge setup

These instructions are for a simple virtualenv-based setup. You can also set up with Docker, or set up systemd to run the bridge with this virtualenv setup.

Requirements

  • Python 3.7 or higher with pip and virtualenv.
    N.B. Python 3.8 will be the minimum in the near future.
  • A Matrix homeserver that supports application services (e.g. Synapse). You need access to register an appservice, which usually involves editing the homeserver config file.
  • A PostgreSQL server (which you should already have for Synapse).
  • If installing optional dependencies, see the optional dependencies page.
  • mautrix-telegram: Telegram app ID and hash (get from my.telegram.org).
  • mautrix-signal: An instance of signald.

Production setup

  1. Create a directory for the bridge. Do not clone the repository.
  2. Set up a virtual environment.
    1. Create with virtualenv -p /usr/bin/python3 . (note the dot at the end)
      • You should not use a subdirectory for the virtualenv in this production setup. The pip install step places some required files at the root of the environment.
    2. Activate with source ./bin/activate
  3. Install the bridge with pip install --upgrade mautrix-$bridge[all]
    • [all] at the end will install all optional dependencies. This includes end-to-bridge encryption, which requires libolm3. See the optional dependencies page for more info.
    • If you want the master branch instead of a release, use pip install --upgrade git+https://github.com/mautrix/$bridge.git#egg=mautrix-$bridge[all].
  4. Copy example-config.yaml to config.yaml.
  5. Update the config to your liking. You'll at least need to change the homeserver settings and permissions. If you miss something that's required, the bridge will refuse to start and tell you what's missing.
  6. Generate the appservice registration with python -m mautrix_$bridge -g. You can use the -c and -r flags to change the location of the config and registration files. They default to config.yaml and registration.yaml respectively.
  7. Add the path to the registration file (registration.yaml by default) to your Synapse's homeserver.yaml under app_service_config_files. Restart Synapse to apply changes.
  8. For mautrix-telegram and mautrix-hangouts only: Initialize the database with alembic upgrade head. If you have a custom config path, use alembic -x config=/path/to/config.yaml upgrade head.
  9. Run the bridge python -m mautrix_$bridge.

Upgrading (production setup)

  1. Make sure you're in the virtualenv (source ./bin/activate).
  2. Run the bridge install command again (install step #2).
  3. For mautrix-telegram and mautrix-hangouts only: Update the database with the command in install step #7.

Development setup

  1. Clone the repository.
  2. Optional, but strongly recommended: Set up a virtual environment.
    1. Create with virtualenv -p /usr/bin/python3 .venv
    2. Activate with source .venv/bin/activate
  3. Install dependencies with pip install --upgrade -r requirements.txt
    • Optionally, add -r optional-requirements.txt to install optional dependencies. Some of the optional dependencies may need additional native packages. See the optional dependencies page for more info.
  4. Continue from step #3 of production setup.

Upgrading (development setup)

  1. Make sure you're in the virtualenv (source .venv/bin/activate).
  2. Pull changes from Git.
  3. Run the dependency install command again (install step #2).
  4. For mautrix-telegram and mautrix-hangouts only: Update the database with the command in install step #7.