Python bridge setup

Select bridge:

Generic instructions mautrix-telegram mautrix-whatsapp mautrix-googlechat mautrix-twitter mautrix-bluesky mautrix-signal mautrix-discord mautrix-slack mautrix-gmessages mautrix-meta mautrix-gvoice

Please select a bridge above. If you don't select a bridge, you'll have to manually replace occurrences of $bridge with the correct name before running commands. The selector requires JavaScript to replace text.

This page contains instructions for setting up the bridge in a virtualenv. You may also want to look at other ways to run the bridge:

• Docker
• YunoHost: mautrix_telegram_ynh,
• systemd service (at the bottom of this page)

Please note that everything in these docs are meant for server admins who want to self-host the bridge. If you're just looking to use the bridges, check out Beeper, which provides fully managed instances of all of these bridges.

If you need help with setting up the bridge, you can ask in the Matrix room: #$bridge:maunium.net. For help with setting up other parts like the homeserver that aren't the bridge, refer to their documentation to find support rooms.

Requirements

• Python 3.10 or higher with pip and virtualenv.
• 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, v10 or higher (which you should already have for Synapse).
  • Make sure you don't share databases between unrelated programs. Shared postgres instance is fine, but shared database is not.
• If installing optional dependencies, see the optional dependencies page.
• mautrix-telegram: Telegram app ID and hash (get from my.telegram.org).
• mautrix-telegram: LottieConverter if you want animated stickers to be converted to something viewable on Matrix.
• Bridges with voice messages: ffmpeg to transcode audio files (just install it with your system package manager).

Production setup

Don't use sudo for any of these steps (and preferably don't use the root user either).

0. Create a directory for the bridge. Do not clone the repository.
1. 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
2. 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 mautrix-$bridge[all]@git+https://github.com/mautrix/$bridge.git.
3. Copy example-config.yaml to config.yaml.
4. Update the config to your liking. See the initial bridge config page for recommendations.
5. 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.
6. Register the bridge on your homeserver (see Registering appservices).
7. Run the bridge python -m mautrix_$bridge.

Upgrading (production setup)

0. Make sure you're in the virtualenv (source ./bin/activate).
   • Note: if you updated Python, you'll have to recreate the virtualenv to apply the update.
1. Run the bridge install command again (install step #2).

Development setup

0. Clone the repository.
1. 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
2. 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.
3. Continue from step #3 of production setup.
4. For linting: pip install -r dev-requirements.txt to install Black, isort and pre-commit, then install the Git hook with pre-commit install. This will ensure that code is properly formatted when you commit, to avoid having to fix linting errors when the CI complains.

Upgrading (development setup)

0. Make sure you're in the virtualenv (source .venv/bin/activate).
   • Note: if you updated Python, you'll have to recreate the virtualenv to apply the update.
1. Pull changes from Git.
2. Run the dependency install command again (install step #2).

systemd service

1. Create a user for the bridge:

   $ sudo adduser --system mautrix-$bridge --home /opt/mautrix-$bridge
   

2. Follow the production setup instructions above. Make sure you use that user and home directory for the bridge.
3. Create a systemd service file at /etc/systemd/system/mautrix-$bridge.service:

   [Unit]
   Description=mautrix-$bridge bridge
   
   [Service]
   # N.B. If you didn't create a user with the correct home directory, set this
   #      to the directory where config.yaml is (e.g. /opt/mautrix-$bridge).
   WorkingDirectory=~
   ExecStart=/opt/mautrix-$bridge/bin/python -m mautrix_$bridge
   User=mautrix-$bridge
   
   [Install]
   WantedBy=multi-user.target