Welcome to Matrix User Documentation¶

1 Frequently Asked Questions (FAQs)¶

If your question isn’t answered here try the Matrix.org FAQ or the Matrix Knowledge Base.

Contents

1 Frequently Asked Questions (FAQs)
2 Matrix
3 Riot

Federation means that all Matrix servers are able to send messages to each other. It means that it doesn’t matter if you join a large public server or self host, you can still talk to anyone on any other server.

See also Wikipedia’s article on federation. Note that the dictionary definiton of federation often reads something like “a group of states with a central government…”. This is not how the term federation is used when talking about computers. Matrix has no central server. Matrix.org is just like any other server that speaks the Matrix protocol, it has no special powers, authority, or meaning.

2.2 Where are rooms stored?¶

Rooms are stored on all homeservers that participate in the room. If one server goes down, it only affects the users that have their accounts on that server. For example if matrix.org goes down, matrix.org users won’t be able to talk but everyone else in #matrix:matrix.org can continue talking. When matrix.org comes back up its users can start talking again and will be able to see the messages that were sent while it was down.

But the room ID you say. “It is !QtykxKocfZaZOUrTwp:matrix.org. You see, right there it says matrix.org, that means that is a matrix.org room! This is centralized after all!” No that’s not what that means. Matrix rooms need a unique identifier since room aliases can be reassigned at any time. That is just an unique room ID. It is a federated system, so to ensure that the ID is unique the room ID includes the name of the server that created it. It is possible that the server mentioned in the room ID may not even exist anymore. The room still works just fine.

2.3 What client should I use?¶

2.4 What is the difference between Matrix and Riot?¶

2.5 What are room tags?¶

You can use room tags to organize your rooms. The default tags are called favorites and low priority. In Riot, you can mark a room as a favorite and it then be moved to the favorites section. Rooms can have multiple tags but some clients (namely Riot) will only put a room in one section. Quaternion and https://tags.t2bot.io are two clients that support creating room tags.

2.6 What are room versions? What does room version 4 (or 5) give me?¶

Ideally room versions wouldn’t need to exist but there were some bugs that were found in the way rooms worked initially. Additionally there have recently been a lot of ideas about how to make Matrix even more decentralized and private. With portable accounts you could log in to any Matrix server and wouldn’t be stuck if the one you signed up for went offline. For both of these reasons, some things about how rooms work had to be changed. Room versions just describe how your room works, which algorithm it uses and

2.7 Should I upgrade to room version 4 (or 5)?¶

Probably not yet. All versions other than version 1 (the default) are still in testing. Even once they are stable, upgrading a room isn’t a seamless transition. Users are not automatically put into the new room. In public rooms users will get a link to join the new room. In invite only rooms, users have to be manually invited. The upgrade process is really only designed for public rooms. Most private rooms should stay on the version they were created with.

Also note that while all well behaved clients should work with any room versions, only Riot and Quaternion support the room upgrade process.

3 Riot ¶

3.1 What is Riot?¶

3.2 What are the people and room sections? Can I create custom sections (room tags)?¶

The people and room sections are just there to help you organize your rooms better. There is no difference between the rooms in any section. You could mark a room with 1000 people in it as a direct chat so it showed up in the people section or you could remove the direct chat tag from a room where you were just talking to one other person.

3.3 What is a device?¶

3.4 Why does my device ID change all the time?¶

You probably logged out (or have your browser set to clear out everything when you close it). Riot is designed for you to stay logged in. You should only sign out if you are using Riot on someone else’s computer.

What is Matrix?¶

Getting Started with Matrix¶

Which Matrix client should I use?¶

What’s Next?¶

Matrix User Documentation¶

Another Matrix documentation project. I know, there are several however none of them aim to actually be a handbook for using Riot or any other clients. I would like for this to become a place where you can find “The (unofficial) Riot Handbook” or “The (unofficial) Quaternion Handbook” as well as a place where you can find answers to more of your FAQs. I’m still working on writing these but would love help from the community.

Even if this just ends up being a place for me to store my canned answers to Matrix related questions, I’ll consider that a success. I have tried to contribute to other related projects like matrix-knowledge-base but Coffee seems to be MIA at the moment.

You can view the most up to date version of the documentation online at http://mud.raim.ist/en/latest (for some reason https isn’t quite working yet).

You can also download the documentation in HTML, PDF, or Epub formats from: https://readthedocs.org/projects/matrix-user-documentation/downloads/

How to contribute¶

git clone https://github.com/aaronraimist/matrix-user-documentation.git

cd matrix-user-documentation

virtualenv -p python3 env
source env/bin/activate
pip install -r requirements.txt

make livehtml

Make your changes and watch them at http://127.0.0.1:8000/. When you are ready to submit a pull request you can optionally run doc8 which will tell you if you have any style issues. The main thing to note is that the maximum line length for anything other than titles is 72 characters. If you don’t fix these style changes before you submit, I’ll fix them for you.

You can check for dead links with

make checklinks

Why does this use reStructuredText?¶

Yeah I know. I don’t really like it either but it turns out using Markdown for documentation isn’t a great idea.

Riot ¶

Riot could be considered the flagship Matrix client. It is made by many of the same people that write the Matrix spec but it is just one Matrix client. Your account works with any Matrix client. You can find many more using Try Matrix Now

Riot Web / Desktop ¶

Riot web is…

Riot Android ¶

Riot Android is a native Matrix client for Android.

RiotX ¶

RiotX is the code name for the future version of Riot Android. It is a rewrite of Riot Android written in Kotlin and a new radically different UI.

What is RiotX¶

RiotX is just the future version of Riot Android. It is a complete rewrite to make it more performant and to completely change the interface. RiotX is just a name to seperate it from Riot Android while it is being developed. It will become Riot Android in the future.

Riot iOS ¶

Riot iOS is a native Matrix client for iOS.

Bridges¶

Glossary¶

Dendrite: Dendrite is…
End-to-End Encryption (E2EE): Encryption is…
Federation: Federation is
homeserver: The homeserver is where your Matrix account lives. Homeservers store your account data and the rooms you participate in.
Matrix: Matrix is…
Quaternion: Quaternion is…
Riot
Riot Web / Desktop: Riot Web is…
Riot Android: Riot Android is…
Riot iOS: Riot iOS is…
RiotX: RiotX is…
Ruma: Ruma is….
Synapse: The reference Matrix homeserver

Servers¶

Note

Currently the only usable server is the reference implementation, Synapse. Developers are hard at work on Dendrite, Ruma, and others but they aren’t quite ready yet.

matrix-docker-ansible-deploy¶

If you are trying to install a Matrix server, the best way to install Synapse is using matrix-docker-ansible-deploy. In minutes, it will give you a 100% correct Matrix installation with very little effort. You’ll get everything you need: Synapse (the reference Matrix homeserver) configured to use a PostgresQL database, coturn for audio calls, Riot (a nice web client), nginx, a mail server, and much more but you can easily disable any of those. This way of setting Synapse up also has some of the best documentation anywhere in the Matrix community. If you find an easier way to install Synapse, call me. Until then, this is the easiest.

Official Installation Guide¶

If you are scared of Docker or Ansible, don’t be, it isn’t that hard… but if you still are then you can install Synapse using it’s official installation guide. Just remember that I warned you. There are going to be a lot of manual steps you’ll need to do to get a good setup whereas the above does it all for you.

Tip

There are many other tutorials on the internet since Synapse has been around for several years. However you should be aware that a lot changed in Early 2019 to make sure everything was production ready. If the tutorial you are looking at was not written or updated in February 2019 or later, then you should not follow it.

Matrix User Documentation is a community run project that hopes to document Matrix from a user’s perspective. This is not official documentation from the Matrix core team.

If you are a developer trying to make a Matrix client or server, you should check out the Matrix Spec instead.

Let’s dive in¶

Where are you in the process of learning about Matrix?

Indices and tables¶

Index
Search

Want to contribute to the documentation?

That’s awesome. Thank you. It’s all right here: https://github.com/aaronraimist/matrix-user-documentation. Fork it, make a change, and submit a pull request.

Have questions or want to discuss it first? Join our Matrix room.

#matrix-user-documentation:raim.ist Matrix Room