Tag: linux

For those of you who do not know, Matterbridge (https://github.com/42wim/matterbridge/) is an application that bridges two or more channels/rooms from 1 or more chat platforms to each other so that users in each can talk to each other.

Being a statically linked, single binary, installation is fairly easy. Configuration is also fairly simple. However some people know more then others. This guide will is intended to help anyone host their own bridge.

---

Table of contents

• Installing
  • Install on Windows
  • Install on Linux
• Building your config
  • Discord
  • Telegram
  • Matrix
  • Config-Gateways
• Additional help

Install on Windows

Go to https://github.com/42wim/matterbridge/releases/ and Download the binary for your system. This is most likely going to be windows-64bit.exe. Put it into the folder of your choice. I would recommend making an empty folder, but it is not required that you do so. Open a command Windows by clicking an empty part of the windows to make sure nothing is selected. Them press shift+right-click and select either “Open in Windows Terminal”, or “Open Powershell Window Here”.

This should open a command window that you can run the app in. Run .\matterbridge-1.22.2-windows-64bit.exe in the command window. If all is well, you should see an error like the one below saying that it cannot load the config file. This is normal as we have not created it yet. Proceed to the Configuring section to build the config file.

Installing under Linux

In your favorite browser, https://github.com/42wim/matterbridge/releases and download the binary for your platform. In my case, it is matterbridge-1.22.2-linux-armv6. Put it in the folder of your choice. I prefer to put it in a dedicated directory, but that is up to you.

From a command shell, make it executable by running chmod +x matterbridge-1.22.2-linux-armv6, replacing matterbridge-1.22.2-linux-armv6 with the file you downloaded. Run it with ./matterbridge-1.22.2-linux-armv6, substituting as necessary. If all is well, you should get an error saying that it cannot read the config file. We will build it next.

Other platforms

I do not have other systems to test it on. However, the commands are likely to be similar to the ones for Linux. I also expect that you know more about your system that I do, and that you know how to download a file and run and application on it.

Building your config.

Steps for all possible platforms are available at https://github.com/42wim/matterbridge/wiki/How-to-create-your-config.

Matterbridge uses gateways to bridge different protocols together. Gateways are like a hub where messages are sent to, then copied by each protocol driver. Multiple gateways can be configured, and one instance can have multiple gateways running. A protocol can be setup multiple times. Each configuration on a protocol is called an instance throughout this guide.

Discord

Based off of https://github.com/42wim/matterbridge/wiki/Section-Discord-%28basic%29

Discord messages are relayed using bots. You can create a discord bot by going to https://discord.com/developers/applications and clicking new application. Name the app when prompted.

One the app is created, you will be taken to the general information page. Here you can Rename your app or give the app an optional Description and image. You can change the information here at any time. Once you are ready, click the Bot link on the left side to open the Bot page.

On the Bot page, click Add Bot, then Yes, do it!. This will create a new bot. You can also create a new bot on an existing app as well.

We are now ready to create the configure Matterbridge to use the bot. Create a config file if you haven’t already. Paste the following code snippet near the top of the file.

[discord.mydiscord]
# You can get your token by following the instructions on
# https://github.com/42wim/matterbridge/wiki/Discord-bot-setup
# in particular that the "Members Intent" checkbox is important.
# If you want roles/groups mentions to be shown with names instead of ID, 
# you'll need to give your bot the "Manage Roles" permission.
Token="YOUR_TOKEN_HERE"
Server="name or uid of guild" # picked from guilds the bot is connected to
RemoteNickFormat="[{PROTOCOL}] <{NICK}> "

Replace YOUR_TOKEN_HERE with the bot token. You can get it by clicking Copy button which will copy the token to your clipboard. Paste it into the config file. We will get the server id next.

In order for the bot to work, you need to enable Server Members Intent. Scroll down to Privileged Gateway Intents and enable the Server Members Intent switch.

Now you will need to add the bot to the server you want to bridge. Click the OAuth2 button and select bot under scopes, then click the Copy button. This will give you the URL to add the bot to the server with. Paste it in a browser tab and press enter to go to the page.

Select the server that you want to add the bot to from the dropdown and click Authorize. Note: You will need to have Manage Server permission on the server to add the bot to it.

Once the bot is added, you will need to get the server ID. To do so, go to your user setting > Advanced and enable Developer Mode.

Close the Settings page and open the server you added the bot to. Right+Click on the server name and click Copy ID. Just clicking on the Server name will not work. Go back to the config file and set the Server field to the ID you just copied. You are now ready to add the instance to a Gateway. Set the Channel in the gateway to the Channel name in the server.

TODO: Write out a detailed tutorial for Telegram.

Telegram

Based off of https://github.com/42wim/matterbridge/wiki/Section-Telegram-%28basic%29

Telegram messages are relayed using bots. Full instructions to create a bot are at https://core.telegram.org/bots#6-botfather.

To create a bot, start a chat with @botfather in Telegram. Click start to begin a conversation. Send /newbot. Give it a name and a username. Usernames are 5-32 characters long and are case insensitive, but may only include Latin characters, numbers, and underscores. Your bot’s username must end in ‘bot’, e.g. ‘tetris_bot’ or ‘TetrisBot’.

Next, you need to set the Privacy mode of the bot to disabled for Mattermost to work properly with the bot. Otherwise it will only relay mentions. Do so by sending /setprivacy. Select Disable when prompted.

Add the following template to your config. Replace Yourtokenhere with the token you got from BotFather.

[telegram.mytelegram]
#See https://core.telegram.org/bots#6-botfather 
#and https://www.linkedin.com/pulse/telegram-bots-beginners-marco-frau
Token="Yourtokenhere"
RemoteNickFormat="({PROTOCOL}) {NICK} "
MessageFormat="HTMLNick"

Matrix

Creating a Matrix bridge could not be more simple. First, create a dedicated user for your bot. This is not required, but Matterbirdge will not relay messages from the account it is logged in as.

Second, paste the following code block into your config, filling in the appropriate fields

[matrix.mymatrix]
#Server is your homeserver (eg https://matrix.org)
Server="https://matrix.org"
#login/pass of your bot.
#Use a dedicated user for this and not your own!
#Messages sent from this user will not be relayed to avoid loops.
Login="yourlogin"
Password="yourpass"
RemoteNickFormat="[{PROTOCOL}] <{NICK}> "
#Whether to send the homeserver suffix. eg ":matrix.org" in @username:matrix.org
#to other bridges, or only send "username".(true only sends username)
#OPTIONAL (default false)
NoHomeServerSuffix=false

Last, you will need to get the room ID. While the room name sometimes works, I have not had much success with it. To find it in Click on the room name > Advanced, and save the Internal room ID field. This is what you will use for the channel later.

Configuring your gateway(s)

One of the nice things about Matterbridge is that is supports having multiple gateways, and multiple bridges in each gateway.

To create a gateway, go to the bottom of the config and create a gateway, using the following as a sample. Replace protocol with the protocol name, and myprotocol with the bridge name. Repeat with as many gateways as you want. Just make sure to give each gateway a uniqure name.

[[gateway]]
name="gateway1"
enable=true
[[gateway.inout]]
account="protocol.myprotocol"
channel="prtocolchannel"
[[gateway.inout]]
account="protocol2.myprotocol2"
channel="protocol2channel"

TODO: Write out a detailed tutorial for Mattermost.

TODO: Write out a detailed tutorial for IRC.

Additional help?

We have discussions at the Github repro. https://github.com/42wim/matterbridge/discussions. You can also read and open bugs on the issue tracker at https://github.com/42wim/matterbridge/issues. You can also chat with community members on any of several chat apps. https://github.com/42wim/matterbridge/#chat-with-us. Each room is bridged to each other using Matterbridge.