Slack <=> Discord bridge with Matterbridge

matterbridge.md

Slack <=> Discord bridge with Matterbridge

This is a tutorial to get an instance of Matterbridge running on a machine using Docker and docker compose.

What is Matterbridge?

Matterbridge is an open-source and self-hosted application that acts as a bridge between different chat platforms. It can connect a variety of services, such as Slack, Discord, Matrix, Telegram, IRC, and more. This means that users on one platform can communicate with users on another without joining each other's servers or networks. Matterbridge is capable of mirroring text messages, files and images across platforms.

Options for hosting

• Heroku's Github Students plan (Credit card required) (Template for deploying?)
• fly.io's Hobby plan (Credit card required)
• Microsoft Azure student credits (Guide for deploying?)
• Amazon AWS student credits
• Running it on your hardware (optionally with Docker and docker compose) - you need to ensure this stays online all the time

This guide will focus on the last point - self-hosting - for now, as I'm slightly crunched on time, and this is the deployment method that I have chosen. If you need any help with the other options or just help with this in general, feel free to join the ECSE Discord server and ask there - I haven't tried to deploy to another service yet though

Prerequisties(?)

Docker is an open-source platform that automates application deployment, management, and scaling using containerization technology. Containerization allows developers to package an application and all its dependencies into a standardized unit called a "container." These containers provide a consistent and isolated environment, ensuring the application runs reliably and consistently across different environments. I'm running this on an Ubuntu server; the install process for Docker would be different if you're on macOS or Windows - I only use Docker in a server environment, and I'm unclear about the process of using Docker Desktop.

Docker is not strictly required. You could probably download a binary from here and run Matterbridge in the command line by using ./matterbridge-<version>-<os>-<platform> Docker is another layer of complexity that might not be worth the hassle of setting up.

Creating the applications

Luckily for us, Slack and Discord are popular, and the Matterbridge Wiki has guides to create a bot application for both of these:

Make sure you read and follow the guides carefully; there are crucial steps in the Slack bot setup Ignore the parts where it tells you to add to the Matterbridge configuration - we will do this at the end. Make sure to copy your Discord and Slack bot tokens and paste them into a Notepad window or something.

• Follow the steps here to create a Discord appplication
• Follow the steps here to create a Slack application

Adding the Slack bot to a workspace requires an Admin to approve your integration before you can get a Slack bot token.

Assuming that you've followed the above guides and your integration has been approved, you should now have both a Slack and Discord bot token.

Creating your Matterbridge.toml configuration

Create a folder for your Matterbridge configuration (and binary file - if you're not using Docker). Copy our (below) configuration into a new file named matterbridge.toml and edit it to suit your needs

[slack]
[slack.ece209-team-01]
Token="<Slack bot token>"
PreserveThreading=true
RemoteNickFormat="{NICK} - Discord"

[discord]
[discord.ece209-team-01]
Token="<Discord bot token>"
Server="<Server ID>"
PreserveThreading=true
RemoteNickFormat="[`{NICK}`] "
AutoWebhooks=false

[[gateway]]
name="ece209-team-01"
enable=true

[[gateway.inout]]
account="Slack.ece209-team-01"
channel="ec209_2023_team_01"

[[gateway.inout]]
account="discord.ece209-team-01"
channel="slack-bridge"

• Replace <Slack bot token and <Discord bot token> with your Slack/Discord bot tokens that you created earlier
• Fill in your Discord server ID by right-clicking on any channel in your server and copying the URL to the channel, e.g. https://discord.com/channels/908944607344214106/908944607344214109. Your Discord server ID is the first set of numbers after discord.com; in this case, it is 908944607344214106
• Replace the channel at the bottom with the names of your Slack and Discord channels.

Running

If you're not using Docker, you can start the command prompt in the current directory and run Matterbridge in the command line by using ./matterbridge-<version>-<os>-<platform>

If you are using Docker, create a docker-compose.yml file and paste the following contents:

version: '3.7'
services:
  matterbridge:
    image: 42wim/matterbridge:stable
#    restart: unless-stopped
    volumes:
    - ./matterbridge.toml:/etc/matterbridge/matterbridge.toml:ro

(Taken from here, auto restart disabled)

If you want Docker to restart when there is a failure automatically, uncomment the restart: unless-stopped line. Note that if there is an issue with your configuration, Matterbridge will exit immediately, and Docker will restart the container immediately, resulting in a restart loop. Discord may invalidate your token if you log in too many times due to the start loop.

To start the docker container with docker compose, start a terminal in the current window and run docker compose up -d --build matterbridge. If you wish to change the configuration, you should restart the container.