synapse-docker-bridges/config/mautrix-discord/README.md

Discord Bridge Setup Guide

This guide will help you set up the Discord bridge for your Synapse Matrix server.

Prerequisites

Before starting, ensure that:

• Synapse is properly configured and running.
• The discord database was created during the initial setup.
• You have your domain name ready.

Setup Steps

1. Navigate to the Discord configuration directory:

cd config/mautrix-discord

2. Generate the initial configuration file:

docker run --rm -v `pwd`:/data:z dock.mau.dev/mautrix/discord

3. Edit the generated config.yaml file. You may need administrative privileges (sudo) to edit this file.

Required Configuration Changes

Make the following modifications to your config.yaml:

Homeserver Settings

homeserver:
    address: http://monolith:8008  # Internal Docker network address
    domain: your.domain.com        # Replace with your actual domain

Appservice Settings

appservice:
    address: http://discord:29334  # Internal bridge address
    hostname: 0.0.0.0             # Listen on all interfaces

Bridge Settings

bridge:
    permissions:
        "*": relay
        "your.domain.com": user           # Replace with your domain
        "@yourusername:your.domain.com": admin  # Replace with your Matrix ID

Database Connection

Update the database URI to use the Discord-specific database:

# Original:
# postgres://synapse:password@postgres/synapse?sslmode=disable

# Modified (note 'discord' database name):
postgres://synapse:password@postgres/discord?sslmode=disable

4. Generate the registration file:

docker run --rm -v `pwd`:/data:z dock.mau.dev/mautrix/discord

5. Configure Synapse to use the Discord bridge by editing config/synapse/homeserver.yaml:

app_service_config_files:
- "/etc/discord/registration.yaml"

6. Start the bridge service:

docker compose up -d mautrix-discord

7. Restart Synapse to load the new bridge configuration:

docker compose restart monolith

Verifying the Setup

Check if the bridge is running:

docker compose logs mautrix-discord

You should see messages indicating the bridge has started successfully. If the configuration files aren't present, the service will remain stopped - this is normal and prevents unnecessary restarts.

Using the Bridge

1. Start a chat with @discordbot:your.domain.com in your Matrix client.
2. Follow the bot's instructions to:
   • Set up a Discord bot account.
   • Add the bot to your server.
   • Link your Discord account.

Double Puppeting

Double puppeting makes messages you send from Discord appear as coming from your Matrix account. To enable it:

1. You'll need the access token that was displayed when you created your Matrix user with the create-user.sh script.
2. Start a private chat with @discordbot:your.domain.com.
3. Send the command: login-matrix <access-token>. (Replace <access-token> with your saved access token from create-user.sh).
4. The bot should confirm successful double puppeting setup.

Note: If you've lost your access token, you can generate a new one using Element or another Matrix client in Settings > Help & About > Access Token.

Troubleshooting

1. Bridge Not Starting

   • Verify that both config.yaml and registration.yaml exist.
   • Check file permissions.
   • Review logs with docker compose logs mautrix-discord.

2. Bot Connection Issues

   • Verify bot token is correct.
   • Check if all required intents are enabled.
   • Ensure bot has proper permissions in Discord.

3. Channel Bridging Issues

   • Verify bot has access to the channel.
   • Check if the channel type is supported.
   • Ensure proper permissions in both Discord and Matrix.

4. Message Delivery Problems

   • Check bridge permissions in config.
   • Verify room configuration.
   • Ensure Discord connection is active.

Next Steps

For more detailed information about bridge features and configuration options, visit the mautrix-discord documentation.