📗 Matrix and Riot Manual

manual

#1

We use the Matrix instant messaging system at Edgeryders for collaborating among our teams on projects. This wiki documents how to use your Matrix ID for communication.

Content

1. Getting a Matrix account

2. Logging in to Matrix / Riot

3. First steps with your Matrix account

4. Advanced topics

5. Edgeryders’ Matrix addressbook


1. Getting a Matrix account

As a collaborator on an Edgeryders project, you’ll need a Matrix account (or more formally, a “Matrix ID”). It’s simple:

  1. Create an edgeryders.eu account. Because your Matrix account username will be the same as your edgeryders.eu username.

  2. Ask @matthias to create an @username:edgeryders.eu Matrix account for you. Ask by direct message here on the edgeryders.eu platform, or by e-mail to matthias@edgeryders.eu. You will receive your password to your e-mail address.

How Matrix IDs look. Similar to e-mail addresses, Matrix IDs have a “localpart” and a “domain part”. The spelling is a bit different than e-mail addresses to avoid confusing them. For Edgeryders, we are running our own Matrix software on our own server, so the “domain part” is “edgeryders.eu”. The “localpart” is always the same as your egderyders.eu username (in all-lowercase).

Do not use a federated Matrix account. To collaborate on Edgeryders projects, please get a @username:edgeryders.eu account as instructed above. Technically it is also possible to get an account at a different Matrix homeserverr (such as :matrix.org, available for free) and to use that to participate in Edgeryders’ Matrix chats. However, we want to avoid that (and enforce that by disabling federation in some Matrix rooms because):

  • There are still some bugs in Matrix for presence notifications across federated servers, means users with an :edgeryders.eu account may not see people with :matrix.org accounts as online, and vice versa.

  • Chat messages in rooms with users from different Matrix homeservers are permanently stored on these multiple homeservers, not just on our own. This is a privacy / confidentiality issue (possibly even clashing with the GDPR), except if we would consistently use end-to-end encryption to enforce that these messages are stored in an encrypted manner. However, there are still some bugs with end-to-end encryption in Matrix, so it’s not advisable to do this.

2. Logging in to Matrix / Riot

In the browser. We have an own Matrix server running, so all your messages are saved only on our own server (except you communicate with Matrix users not in the edgeryders.eu domain!). However, we do not yet have our own application installed to actually use Matrix. That will follow until the creating of Matrix accounts for all Edgeryders users. Until then, you can use the free and open source software “Riot.im” to communicate over Matrix. You can log in as follows (normally you never log out in Matrix, so this is a one-time thing):

  1. Open this link in a new tab / window: https://riot.im/app/#/login.

  2. Choose: “Sign in with: matrix.org Matrix ID” or (if that is not listed) “Sign in with: matrix.edgeryders.org Matrix ID”.

  3. Enter your username as: @username:edgeryders.eu , as found in the e-mail you received or in our “Matrix addressbook” below.

  4. Click in the password field. The software will now automatically change and fill some fields, which is ok.

    (more details)

    In particular, the software will switch the first field to “Sign in with: matrix.edgeryders.org Matrix ID”. It will also choose the “Custom server” option and fill in the "Home server URL as https://matrix.edgeryders.eu:8448.

    If it does not do the last two things, you can still do that yourself. When entering the Home server URL, enter it exactly as given above. Even a small deviation like a trailing slash will make this fail, which is an issue we have reported.

  5. Enter your password (as received in the e-mail from @matthias).

  6. Click “Sign In”.

On a smartphone. To be available on the go, you probably want to install a Matrix client software on your smartphone as well. For that, the Riot.im software is also available as mobile apps for Android and for iOS.

Here is the login procedure for the Android app:

  1. Open the installed app, called “Riot.im”.

  2. Enter your username as @username:edgeryders.eu, as found in the e-mail you received or in our “Matrix addressbook” below.

  3. Enter your password (as received in the e-mail you received from @matthias).

  4. Choose “Use Custom server options (advanced)”.

  5. Enter your home server URL as https://matrix.edgeryders.eu:8448

    (Enter it exactly like that. Even a small deviation like a trailing slash will make this fail, which is an issue we have reported.)

  6. Leave the identity server URL as it is: https://vector.im.

3. First steps with your Matrix account

After log in, here are some first steps to do in the Matrix software:

  1. Accept the invitations. Your Matrix account has already been invited to one or several rooms by the admin who created your account. So, please accept the invitation on the left side of the screen (when using Matrix in your browser). Attention: The “Campfire” is a public socializing corner where we invite everyone from Edgeryders and our networks with a Matrix account. So please don’t put anything even remotely confidential there :slight_smile:

  2. Adapt your account settings. Click the gear icon in the left bottom part to go to your account settings. There:

    1. Connect an e-mail address. (Note: For now, it will be possible to find your Matrix account under this e-mail address on the vector.im identity server, so use one that you are ok with for this purpose.)

    2. Change your password – this is important, because the one above was not safely transmitted via e-mail. Instructions: (1) first connect an e-mail address, as mentioned above, (2) change the password in the account settings, (3) click the confirmation link in the e-mail sent to your e-mail address, (4) after the confirmation “password successfully changed”, ignore the warning about exporting and reimporting keys since you have not sent or read any encrypted messages by now.

    3. Change your display name – also important, because important functionalities like mentions and invitations do not work as well if you do not do this. By default, you will appear as “@username:edgeryders.eu” in chat logs and as room name of your direct chats, which is ugly. We propose to set the display name to your localpart, so just “username” in this case, to keep things simple. Due to a software bug, you can’t do this in one step yet. So change the display name to something else first, close the settings, then reopen it again and change it to the localpart of your Matrix ID (with lowercase first letter, please!).

    4. Add a profile picture.

    5. Enable e-mail notifications. There is an option in the account settings to do this for the e-mail address you just connected to your account. You will then get e-mails about messages received while you were offline / unresponsive.

    6. Enable @all notifications. To get everyone’s attention in a long-running team chat where most people have set the notification level to “Mentions only”, this is a nice trick. In line “Notifications → Messages containing keywords”, click on “keywords” and enter “@all” (without the “”). Confirm, then set “Messages containing keywords” to “Noisy”. You’ll see a red message and get @mention equivalent notifications when somebody types @all.

    7. Enable “New Composer & Autocomplete”. (Optional.) To get nice but “experimental” buttons for adding simple formatting to your messages, and for adding emojis with autocomplete after typing a colon “:” and a keyword.

    8. Reduce the default notification level to “Mentions only”. This is ok for a team chat if you want to reduce notification frequency. You’ll still see red bubbles with “new messages” counters in chats so you can catch up, but you will only get notifications (little desktop overlay window, sounds, e-mail message) for your @username mentions and for @all. To set this up, mouse over the “Open Village MENA: Team” room in the room list, click the “…” on-hover button and choose “Mentions only”.

    9. Mobile app: Shorten the “sync request delay” time. In the Android mobile app, this is done under “☰ → Settings → Delay between two sync requests”. The default value is 600 s. Set it to around 60 s instead. Otherwise, you would get all messages 10 minutes (!) after they are sent in cases when Matrix is not the Android foreground app. And that probably includes “when the screen is locked or off”.

4. Advanced topics

4.1. Formatting your content

Formatting messages. Matrix messages support basic Markdown syntax for formatting – see the complete syntax reference. Some is also available from buttons after enabling the “New Composer & Autocomplete” option in your account settings. Some is not, for example the code for proper hyperlinks: to create a link like this, you would write this text into your message: [like this](http://example.com/).

Emojis. With the “New Composer & Autocomplete” option enabled in your account settings, you get emoji auto-complete after typing a colon “:” and the start of an emoji’s name. The complete list of named emojis is available in an emoji cheat sheet and the emoji codes reference. (Images may look slightly different though, as Riot uses an EmojiOne emoji font in a different version, probably the last fully open source version EmojiOne v2, here on Github.)

  It is even possible to include emojis into your display name – they will show up as little colorful images whenever your username is displayed. You configure this either by putting the equivalent Unicode character (like the one for “ghost”) into the “Settings → Display name” field. Or by doing the same with a slash command and the emoji code in a message: /nick someword :ghost:. This also means that when mentioning your display name, the emoji has to be included for a mention notification to work! Not a problem when only appending the emoji to a normal text username, as people can use autocomplete for mentioning. And esp. not a problem when keeping the textual part of such a username the same as the localpart in @localpart:edgeryders.eu, as then the mention will also work when somebody omits the emoji, as it’s still a valid Matrix ID, and mentions also work for these.

4.2. Posting pictures and files

Sharing images and other files. It is possible to share any files to a chat room, using the “Upload File” button in the message editor. Uploaded images will be displayed inside the chat, other uploaded files will be offered for download. When the chat is end-to-end encrypted, the files will also be saved encrypted on our server, in which case nobody outside of the chatroom (not even the server admin) can access their content. Please delete the messages with large files (>1 MiB) after the other people in the chat downloaded them. It will help us keep the backup sizes small. Even better is to upload the files to a shared folder (like, Google Drive) and to only post the link to them in the chatroom.

Posting images from the clipboard. It is possible to post images to a chatroom from the clipboard, which is faster for sharing images than to save an image from the browser to a file first. Tested with Chrome / Chromium 60. Instructions:

  1. In your browser, right-click on the image you want to share in the chatroom.
  2. Click “Copi image”.
  3. Right-click in the Matrix chat message editor and select “Paste” (or just press Ctrl+V while the keyboard focus is on the chat message editor).
  4. A popup window will appear asking if you want to upload the image from your clipboard to share i in the chatroom. Confirm that.

4.3. Getting people’s attention

Getting people’s attention. We’ll have to experiment to find best practices for a long-running team chat without constant notification spam. The current proposal is this one though: Assume everyone in the project team chat has notifications set to “Mentions only” for this room. They will probably catch up with all messages at some time, but you can’t rely on that. So use mentions to get their attention – username, Username, @username and @username:edgeryders.eu all work and produce a red message on the receiver’s side, and a notification (desktop notification, sound, e-mail after 10 minutes). Please note: when you try to mention someone who has not changed their default display name, autocomplete will not work, and you will have to type the whole @username:edgeryders.eu. When you really need the attention of everyone in the chat, you can use @all to the same effect, assuming everyone made the required keyword notifications setup as described above.

How e-mail notifications work. After setting up your Matrix account as instructed above by connecting your e-mail address and enabling it as a notification target, you will receive e-mail notifications about Matrix messages you received while offline, or that you rceived but did not yet read in your browser / mobile app. Quite similar to how it works with Facebook messages. In more detail, the timers work like this for each Matrix “room” individually (however if any e-mail is sent, it will include all accumulated e-mails from all rooms!):

  1. A first e-mail is sent 10 minutes after you received the first message while offline, or after 10 minutes of not reacting to browser / phone notifications.

  2. A second e-mail is sent 10 minutes after the first if there are any new messages since the first one.

  3. No new e-mails are sent for the next 12 hours, after which this whole three-step timer process is started again.

4.4. Creating and managing rooms and chats

Creating rooms and one-to-one chats. If you want a private channel to interact with one other person, create a chat. Chats are always between two people, and two only. Their advantage is that they treat every message as if it contained a mention, so the person you are chatting with will see the notification of every message you send. If you want a thematic space to talk to more than one person, create a room. To do so, locate the menu on the bottom left of your window. The + icon creates a new room; the person icon creates a chat.

Inviting people to a room. Once a room has been created, you will need to invite people to join it. Click on the room from the list on the left, then click the “Invite to this room” icon on the bottom right of the window. Invited people appear in a list on the right side of the window. Please note: when you try to invite someone who has not changed their default display name, autocomplete will not work, and you will have to type the whole @username:edgeryders.eu.

Customizing rooms. Click the cog icon next to the room name to change the settings. We recommend to upload a nice avatar for it: you can do so by clicking the camera icon under the avatar (the default avatar is a circle with the first letter of the room’s name). The camera icon is only visible after clicking on the cog (settings) icon. We also recommend you set a color for the room that is in line with the avatar. This way, people have a visual cue as to which room they are writing in.

Room administration actions. As a room’s administrator, you have the options to “mute”, “kick” and “ban” users, also accessible with slash commands of the same name:

  • “Mute” means the user stays in the room and can read but not contribute any more.

  • “Kick” is forcing a user to leave the room, just as if they had chosen the “leave” action by themselves. Means, they can re-join at will (if it’s a public room) or when invited.

  • “Ban” means a forced leave, and the user is prevented from re-joining until the admin uses an “unban” command.

Getting more help. The “official” documentation of the Riot client to Matrix, which we use, is here.

4.5. Voice calls, video calls, screensharing

Matrix includes functions for voice and video calls. The one-on-one calls work pretty well, and you can just use them. But the conference calls feature is not mature at all and will not be finished, so we use Zoom and sometimes Google Hangouts for group / team calls etc…

Fixing “Could not connect media”. In case a one-on-one voice or video call does not work for you with an error message “could not connect media”, try the following:

  1. Simply try calling again. Usually, this happens due to intermittent network failures, esp. network congestion, either in the local wi-fi networks or the WAN / Internet. Otherwise:

  2. Disable P2P connections. Click the lower-left gear icon to go to the user settings screen, and there enable the option “VOPI: Disable Peer-to-Peer for 1:1 calls”. Both parties of a call have to do this before the call. This should work around firewall issues that can prevent direct connections between computers on the Internet; such issues can happen when you are in a university network or other heavily managed / protected network. (However, this tip is experimental. Tell in the comments below if it helped.)

Screensharing. Matrix / Riot supports screensharing in calls, but like voice and video calls it is only properly usable for one-on-one calls. It works with recent Firefox and Chrome versions like this:

  • If the screen-sharing user’s browser is Chrome (or Chromium), he or she has to start it with a special command line option (details). For example:
    chromium-browser --enable-usermedia-screen-capturing

  • In the Riot web application, press the “Shift” key and then click the videocall button.

  • Confirm you really want to share your screen. (More on screensharing safety.)

More details about this process here. It works well when screen-sharing from Firefox or Chrome, and receiving in Chrome (should also work in Firefox, but it had issues at times).

4.6. Voice messaging

When communicating over a low-bandwidth Internet connection with undependable quality, voice calls in Matrix / Riot or otherwise will not be of much use as it will be hard and often impossibe to understand each other. Here, sending voice messages back and forth in a Matrix chat is a nice solution.

Voice messages are just audio files uploaded from the local computer. Those in formats MP3, OGG and WAV (and perhaps more) will then get an embedded player right in the Matrix chat. For the file format, we here go for Vorbis files (.ogg) at the lowest quality (0), which means 64 kbps and results in a file size of ca. 360 kB per minute when using one audio channel. That audio quality is good for voice messages, file size is as well compact.

So we only need an efficient workflow to record and upload these audio files, and we’re good to go – see the instructions below.

Remaining issues. In the setup as documented below, a few issues remain:

  • Navigation in the soundplayer embedded in Riot does not work. Probably a normal bug. You can download and open the file in another soundplayer to fix this.

  • For uploading voice messages or any other files >2 MiB, a configuration change to our Matrix server is needed.

1. Voice messaging under Linux

Installation and configuration:

  1. Install audio-recorder (instructions).

  2. Start audio-recorder with the command audio-recorder.

  3. In the “Additional Settings → General” screen, disable “Window always on top”.

  4. In the “Additional Settings → Recording Commands” screen, create a OGG recording command with:

    • Title: “Voice message, lossy, 64 kbps”
    • File extension: ogg
    • Command: audio/x-raw,rate=44100,channels=1 ! vorbisenc name=enc quality=0.0 ! oggmux
  5. Using the corresponding option in your window manager, send the window to a specific desktop to prevent it from showing up on all at once.

  6. Create a bookmark in your file opening dialogue for the directory where audio-recorder stores its recordings.

Usage:

  1. Make a recording in audio-recorder by pressing start and stop. It is saved automatically.

  2. Click the “file upload” dialogue in Riot to upload the recorded file.

  3. Use your bookmark to navigate to the directory with the recordings and choose the newest one.

More documentation:

  • For audio-recorder: open this URL in your browser (tested on Ubuntu 17.04): file:///usr/share/audio-recorder/.

  • For the options of GStreamer vorbisenc, see here.

  • For the quality values of GStreamer vorbisenc: 0.0 - 1.0 correspond to 0 - 10 in the official Vorbis standard – source.

2. Voice messaging under Windows

Installation and configuration:

  1. Visit the Github project “Instruction Guide: fmedia under Windows”.

  2. Download the project as a .zip file, as shown here:

  3. To unpack, install and use the software, follow the installation and usage instructions in the project’s README.

4.7. Sharing login credentials and other secrets

The advised and safest way to share login information of Edgeryders’ accounts for external platforms (e.g. GMail, Twitter, Zoom) is to send it in Riot as follows:

  1. Make sure receiving party is on the Edgeryders Matrix server: mouse over their avatar to show the address and make sure the address ends in :edgeryders.eu.

  2. Start a personal one-on-one chat for this purpose.

  3. Enable encryption for this chat in the chatroom’s settings.

  4. Send the login credentials or other secret information.

  5. Remove the message after the other party confirms they got it. You find that option in the menu of a message, which appears when mousing over it.

In fact this mechanism is much safer than sending a password by (unencrypted) e-mail: it is encrypted by HTTPS and by end-to-end encryption, stored in encrypted form, and is deleted after use from our server, with no copies ending up on other servers. (The latter is why this process should only be used for @username:edgeryders.eu Matrix IDs.)

4.8. Other tips and tricks

Fixing online status issues. If you see somebody posting while they are shown as “offline” in your Riot application’s sidebar, it is usually because they are posting from a device you did not verify. Click on their user avatar icon, and verify the device they are currently using, or all devices. Do it either “the right way” (confirming in a voice call that the keys match), or just click “verify” if you don’t care about encryption integrity in this chat.

Slash commands. Similar to good old IRC, Matrix supports some commands. With the “New Composer & Autocomplete” enabled in your account settings, type a slash “/” at the beginning of a message, and choose from the proposed commands. Most are useful for admins only. The riot.im/app/ stable version provides 8 commands at this time, while the riot.im/develop/ development version has 19.

Using the Riot.im “develop” version. While riot.im/app/ provides the main / stable version of the Riot software, there is also a development version available at riot.im/develop/. It will share a login with the main / stable version, so you can use both in parallel without having to log in again. The develop version is always some days or weeks newer than the main / stable version, so some bugs will be removed and perhaps some new ones will be introduced. Use if you’re an optimist :slight_smile:

5. Edgeryders’ Matrix addressbook

Currently, the following accounts exist on our Matrix server (and no more than these).


:green_book: Discourse User Manual for edgeryders.eu
Using the edgeryders.eu APIs
Multisite login announcement
#6

I think we already need this in the Help and support cat. We are using the Matrix for MENA, but also for the team and basically for everything operational. Agree?


#7

Agreed, and already re-assigned to the “Documentation” cat :cat2: now.


#9

I am so embarrassed to ask this, but I had cleared stuff in my browser lately and now cant remember my password for riot.
When requesting a new one I get:

Error
Failed to send email: This email address was not found

Help?


#10

Just made you a new one, check e-mail (and change it again after login).

Re. your e-mail adress for the account, it seems it has not been properly registered before for notifications etc… Probably because of the bugs in the older versions. Try again after login, adding the e-mail address should work properly now.


#11

Thanks <33


#12

was wondering if anyone is using Android version of Riot, I finally got an android phone as my old windows phone finally died, RIP,but I can’t find the log in via matrix id page. only via email, I tried using my notification mail or matrix id in this field but doesn’t work.

so if anyone got this running can you write some instructions about this.

thanks


#13

@anu, you got this to work right? Could you add instructions to the manual about it?


#14

Sure @matthias :slight_smile:


#15

Hey @hazem. Yes I have been using Riot on my android phone and will update the instructions :slight_smile: Thanks


#16

Hello @hazem I have updated instructions about logging in Riot for android :slight_smile:


#17

I use Riot for Android, @hazem. It works like a charm.

I only had to log in the once, but I remember it was exactly the same as on the desktop, with the nondefault server.


#18

Using Riot on both Ubuntu and Android as @gregoiremarty


#19

@gregoiremarty’s message brings a question to mind: does our Matrix interoperate with the Riot matrix? Could we invite him to one of our rooms? (@matthias).


#20

Yes, that works. We can invite him as @gregoiremarty:matrix.org . The only issue I have seen with this federation feature so far is that the online status notifications are not always accurate.


#21

It works yes. I was actually talking to @unknown_author today and he has an edgeryders.eu matrix account while I’m on the main matrix.


Principles for collaboration and operations in Edgeryders
#22

Thank you @matthias for setting me up and making it so clear in the manual