Skip to main content

Matrix Bridge Implementation

Technical Documentation — matrix.helix9.org — March 2026

Overview​

This document describes the installation and configuration of two Matrix bridges on the self-hosted Matrix homeserver at matrix.helix9.org. The bridges allow Matrix users to send and receive messages from Instagram (via Meta) and Discord directly within any Matrix client such as Element.

Infrastructure​

Server Stack​

See Matrix Homeserver for the full stack (Quadlets, Traefik TLS, federation entrypoint, .well-known delegation). Summary:

ComponentDetails
HomeserverSynapse (matrixdotorg/synapse:latest) on port 8008
Server namematrix.helix9.org
RuntimePodman Quadlets (host network), managed by systemd
DatabasePostgreSQL 16 (postgres:16-alpine)
Reverse proxy / TLSTraefik at 10.69.20.40 (DNS-01 ACME); no in-stack Caddy
Web clientElement Web (vectorim/element-web) on port 8088
FederationTraefik entrypoint :8448 → synapse:8008

Bridge 1: Instagram (mautrix-meta)​

Overview​

mautrix-meta is a Matrix bridge for Meta platforms. It is configured in Instagram mode and runs as a standalone binary managed by systemd.

Installation Details​

SettingValue
Binary location/opt/mautrix-meta/mautrix-meta
Config file/opt/mautrix-meta/config.yaml
Registration file/opt/mautrix-meta/registration.yaml
System usermautrix-meta
Appservice port29319
Bot Matrix ID@metabot:matrix.helix9.org
Bridge databasemautrix_meta (PostgreSQL)
DB usermautrix_meta
Systemd servicemautrix-meta.service
Sourcehttps://github.com/mautrix/meta

Key Configuration​

homeserver:
  address: http://127.0.0.1:8008
  domain: matrix.helix9.org

appservice:
  port: 29319

meta:
  mode: instagram

database:
  type: postgres
  uri: postgres://mautrix_meta:***@127.0.0.1/mautrix_meta?sslmode=disable

Authentication​

Login is performed by messaging the bridge bot and providing browser cookies extracted from Instagram. The recommended method is to copy a cURL command from browser DevTools.

  1. Open a DM with @metabot:matrix.helix9.org
  2. Send: login
  3. In your browser, go to instagram.com (make sure you're logged in)
  4. Open DevTools → Network tab → click any request → right-click → Copy as cURL
  5. Paste the cURL command into the Matrix chat with the bot

Usage​

  • New messages from Instagram will automatically appear as Matrix rooms
  • Only messages received after login are bridged (no backfill of history)
  • To start a new conversation: send pm <instagram_username> to the bot
  • Messages sent to bridged rooms are delivered to Instagram

Bridge 2: Discord (mautrix-discord)​

Overview​

mautrix-discord is a Matrix bridge for Discord. It uses the legacy bridge architecture and runs as a standalone binary managed by systemd.

Installation Details​

SettingValue
Binary location/opt/mautrix-discord/mautrix-discord
Config file/opt/mautrix-discord/config.yaml
Registration file/opt/mautrix-discord/registration.yaml
System usermautrix-discord
Appservice port29334
Bot Matrix ID@discordbot:matrix.helix9.org
Bridge databasemautrix_discord (PostgreSQL)
DB usermautrix_discord
Systemd servicemautrix-discord.service
Sourcehttps://github.com/mautrix/discord

Key Configuration​

homeserver:
  address: http://127.0.0.1:8008
  domain: matrix.helix9.org

appservice:
  port: 29334

database:
  type: postgres
  uri: postgres://mautrix_discord:***@127.0.0.1/mautrix_discord?sslmode=disable

Authentication​

  1. Open a DM with @discordbot:matrix.helix9.org
  2. Send: login
  3. Follow the prompts to authenticate with your Discord account

Synapse Appservice Registration​

Both bridges are registered with Synapse via the app_service_config_files directive in homeserver.yaml:

app_service_config_files:
  - /data/mautrix-meta-registration.yaml
  - /data/mautrix-discord-registration.yaml

Registration files are stored at /opt/matrix/synapse-data/ on the host, which maps to /data/ inside the Synapse container. File permissions must be set to 644 so the Synapse process can read them:

chmod 644 /opt/matrix/synapse-data/*.yaml

Database Setup​

Each bridge uses a dedicated PostgreSQL database on the shared synapse-db container.

DatabaseUser
synapsesynapse
mautrix_metamautrix_meta
mautrix_discordmautrix_discord

To connect to the database container for maintenance:

podman exec -it synapse-db psql -U synapse -h localhost

Systemd Services​

Both bridges run as systemd services for automatic startup and restart on failure.

Common Commands​

# Status
sudo systemctl status mautrix-meta
sudo systemctl status mautrix-discord

# Restart
sudo systemctl restart mautrix-meta
sudo systemctl restart mautrix-discord

# Follow logs
journalctl -u mautrix-meta -f
journalctl -u mautrix-discord -f

Service Files​

  • /etc/systemd/system/mautrix-meta.service
  • /etc/systemd/system/mautrix-discord.service

Updating the Bridges​

mautrix-meta​

cd /opt/mautrix-meta
sudo wget "https://mau.dev/mautrix/meta/-/jobs/artifacts/main/download?job=build%20amd64" -O mautrix-meta-new.zip
sudo unzip -o mautrix-meta-new.zip
sudo chmod +x mautrix-meta
sudo systemctl restart mautrix-meta

mautrix-discord​

Download the latest release from https://github.com/mautrix/discord/releases, replace the binary, then:

sudo systemctl restart mautrix-discord

Troubleshooting​

ProblemSolution
Bridge can't reach SynapseEnsure address is http://127.0.0.1:8008 (not https, not localhost without port)
Permission denied on registration.yamlRun: chmod 644 /opt/matrix/synapse-data/*.yaml
Synapse fails to startCheck logs: podman logs --tail 50 synapse
Bridge not receiving messagesRestart bridge and follow logs: journalctl -u mautrix-meta -f
DB connection errorAvoid special chars in password. URL-encode if needed (e.g. ^ → %5E)
Instagram login failsUse cURL method from DevTools, ensure you are logged into instagram.com

References​