What is Matrix

Matrix is an instant messaging and presence protocol, which is at the crossroads of IRC and Emails with extra glitter. Its main feature is to be a decentralized protocol. It also offers bridges, which have made so many people suffer on IRC side, but it is not its main feature. What follows is a very quick introduction to some of the concepts used in Matrix. If you want a gentle but more extensive introduction, please have a look at this e-mail/Matrix comparison.

Matrix IDs

When you register an email to some email provider, you end up with a user@domain.tld (e.g. alex@coolplace.org) address. This means you are the user alex and your service provider is coolplace.org. You can send emails to andy@chillplace.net. Your inbox exists on coolplace.org, and andy’s inbox exists at chillplace.net.

Matrix works a bit in the same way. People choose a homeserver. Usually newcomers pick matrix.org, which makes it a very crowded place with performance issues. It usually makes a bad first impression, although people are working hard on performance improvements. Imagine if everybody used the same SMTP, the experience wouldn’t be great either.

The people at Element, the company who contributes the most to Matrix, offered to host a Matrix homeserver for GNOME. This allows us to have users on our own homeserver, which is a lot snappier.

We can have andy@gnome.org for Matrix talking to alex@matrix.org, but using an IRC-like interface instead of email. Federated instant messaging! There is another difference: the addresses are not formatted in the same way. A "Matrix address" is actually called a "Matrix ID" or "MXID". They are built as @user:domain.tld, which would make it @andy:gnome.org as an example.

Room IDs

Now why this odd notation for Matrix IDs, while keeping email style notation would have worked, you may ask? Because there is another type of ID in Matrix: the room IDs. The rooms also need to be on one server to easily be reached. A room ID contains two primary information: the room name and the server on which we are going to find it. A Room ID looks very much like a user Matrix ID, except it starts with the same sign as IRC rooms. As an example, this is the room you will automatically join when subscribing to GNOME’s homeserver: #general:gnome.org

The room is a lie

Because of the very decentralized nature of the protocol, a Matrix room rarely only exists on one server. It starts with the server where it was created (say, #coolnewroom:matrix.org). Somebody from GNOME’s homeserver joins and can create a local alias (say #wowcoolroom:gnome.org). This of course will not make the person from GNOME’s homeserver administrator of that room. And of course, it is possible for the administrators of the GNOME homeserver to limit who can create a :gnome.org alias.

What we will do

This tutorial aims at guiding you through the creation of a Matrix account on GNOME’s home server for Matrix, adding the Weechat-Matrix plugin to an existing Weechat installation, and configuring it to use the account previously created.

Weechat-Matrix is a plugin for the Weechat client. That plugin was created by poljar and you find details on weechat-matrix’s repository.

This tutorial was created for Fedora primarily. Some commands may vary depending on the distribution you use when installing packages, but the overall process is the same.

Creating a Matrix account on GNOME’s Homeserver

Important note: GNOME's Matrix instance will only allow you to create an account if you have an e-mail address ending with @gnome.org. If you want to understand why registration has been limited, please have a look at this article covering the reasons in-depth.

1. Open Element io.png

Open gnome.element.io

2. Register information.png

Register your information

3. Verify CAPTCHA.png

Verify the captcha

4. Accept Privacy Policy.png

Accept the privacy policy

5. An email has been sent.png

A confirmation email has been sent

6. After confirmation.png

After clicking the confirmation link you should have this confirmation

7. Skip verify this login.png

Skip the verification step

8. Confirm youre sure.png

Confirm you want to skip it

9. Youre using Element.png

You’re now using Matrix from its web interface Element

Installing the Weechat plugin

10. Install libolm.png

Open a terminal and type:
sudo dnf install libolm{,-devel}

11. Clone and install plugin.png

Clone and build the matrix plugin:
cd ~/Project
git clone https://github.com/poljar/weechat-matrix.git

You can then install the python requirements with
cd weechat-matrix && pip install -r requirements.txt

12. Make install plugin.png

Install with
make install

13. Make it auto start.png

cd ~/.weechat/python
ln -s ../matrix.py ~/.weechat/python/autoload
to get the Matrix plugin started automatically

14. Add GNOME server.png

Launch weechat. Run the command
/matrix server add gnome gnome.modular.im
You read correctly, we can’t use gnome.org just yet because weechat-matrix does not support .well-known auto-discovery yet

15. Set username.png

Configure your username:
/set matrix.server.gnome.username your_username

16. Set password.png

Configure your password:
/set matrix.server.gnome.password your_passphrase

17. Save parameters.png

Save the parameters so they are here at next launch with /save

18. Connect to GNOME.png

You can finally type /matrix connect gnome to connect!

19. Welcome to weechat matrix.png

Congratulations, you’re using Matrix through weechat!

20. Talking in general.png

You automatically join #general:gnome.org, the Matrix-only general channel. Press Alt and the right arrow to come and say hello!

21. Being answered with a quote.png

Formatting is handled a bit differently to make quotes less painful

22. Joining a Matrix only room.png

Now you can join a Matrix only room, such as Sound Recorder’s one by typing /join #sound-recorder:gnome.org. Looks familiar?

23. Posting in the matrix room.png

You can tell the world how happy you are with your new toys!

Adding an IRC server

24. Adding an IRC server.png

Now let’s add an IRC server, because we still have friends hanging over there. Let’s add gimpnet by typing /server add gnomeirc irc.gnome.org

25. Connecting to the IRC server.png

We can now connect to that IRC server with /connect gnomeirc

26. Join gnome hackers.png

Let’s try to join #gnome-hackers with our usual command /join #gnome-hackers

27. IRC responds we need to be authenticated.png

Unfortunately we’re not registered yet, but it’s IRCd answering us with the IRC protocol! All in a single client!

Authenticating manually on IRC servers is cumbersome. Fortunately Weechat has documentation to help you automate that part of your workflow.

28. Explore with fset.png

Intrigued by those /set foo.bar.zor commands? If you want to have a TUI to explore the settings, type /fset

What’s missing

This tutorial is not yet complete. The following bits are missing for now:

  • How about spam?
  • How to find the directory of rooms

ThibaultMartin/WeechatMatrixTutorial (last edited 2021-07-24 20:13:45 by ThibaultMartin)