Differences

This shows you the differences between two versions of the page.

--- services:matrix:start [2020/11/19 10:40] – mention that stickers are still not supported behrmj87
+++ services:matrix:start [2021/09/17 14:53] – more motivation for spaces behrmj87
@@ Line 1: / Line 1: @@
 ====== Matrix ======
+<note tip>This is just the start page of the Matrix documentation, have a look at //More Documentation// section at the bottom.
+If you have questions about Encryption have a look at [[services:matrix:encryption|End-to-End-encryption for Matrix on Element]].
+</note>
 We are running a [[https://en.wikipedia.org/wiki/Matrix_(communication_protocol)|Matrix]] instance. Go to [[https://meet.physik.fu-berlin.de|meet.physik.fu-berlin.de]] to use the web client, where you can log in with your regular Physics account credentials.
 Matrix is an instant messaging protocal, and is accessed by using a client. Analogously to how email is a protocol, and Gmail is a client. Like with email, there are many clients for Matrix. Different people can use different clients to contact each other. A good client to start using Matrix with is Element. You can use the web version of Element at [[https://meet.physik.fu-berlin.de|meet.physik.fu-berlin.de]], or use other versions of [[https://play.google.com/store/apps/details?id=im.vector.app|Android Clients]], [[https://itunes.apple.com/us/app/vector.im/id1083446067|iOS clients]] or [[https://element.io/get-started|Desktop clients]] ([[https://packages.riot.im/desktop/install/win32/x64/Element%20Setup.exe|Windows]], [[https://packages.riot.im/desktop/install/macos/Element.dmg|MacOS]], [[https://flathub.org/apps/details/im.riot.Riot|Linux]]) or any other Matrix client to [[https://matrix.physik.fu-berlin.de|matrix.physik.fu-berlin.de]]
-Upon logging in with your usual ZEDAT credentials for the first time you will be added to rooms according to your group membership.
 Our Matrix server is not federated with the rest of the Matrix ecosystem, due to unresolved privacy questions, but we are giving access to external collaborators upon request.
- Here is a guide for how to use Element.
 ===== First Steps =====
@@ Line 93: / Line 86: @@
 ==== Beyond Text ====
-In the Matrix client we provide, you can do more than write simple text (and uploading files and images). You can style your text with [[https://commonmark.org/help/|Markdown]], including Hyperlinks and syntaxhighlighted code.
+In the Matrix client we provide, you can do more than write simple text (and uploading files and images). You can style your text with [[https://commonmark.org/help/|Markdown]], including Hyperlinks and syntaxhighlighted code. You can also write LaTeX code for math inside dollar signs, e.g. ''$\LaTeX$'' for inline math and ''$$\LaTeX$$'' for display math.
-We hope that TeX for math will be supported soon as well.
 When you hover over one of your messages you get a little context menu, that we will explain now. The buttons are (from left to right) //quick reactions//, //reply//, //edit// and //more options//
@@ Line 147: / Line 138: @@
 If you change your name or profile picture, other users will see it right away, but the menu will only show it once you log out and back in.
+You can also change your name and avatar on a per-room basis. This works only with commands. To change your name, type ''/myroomnick <name>''. To change your avatar in the room, use ''/myroomavatar'', then you will be prompted to choose a file from your computer which will be your new avatar.
 ==== Leaving a room ====
@@ Line 161: / Line 154: @@
 Press "Share room", and you will be presented with multiple means of sharing the room with someone
 {{ :services:matrix:sharing_a_room2.png?600 |}}
-==== Communities ====
+==== Spaces ====
-You might wonder, "I have a group of people, but we also have a set of topics and a single room for that might be confusing!" That is what communities are for, they group people and rooms and can have long descriptions. Unfortunately they are currently **not** searchable, so you have to know about them to navigate to their group page and join them. This should become more comfortable soon™️.
+<note tip>This feature used to be called communities before, but has been supplanted by //spaces// as of late May 2021.</note>
-You can start a new community via the community sidebar <color #ed1c24>(2)</color>.
+You might wonder, "I have a group of people, but we also have a set of topics and a single room for that might be confusing!" Or you might wonder "Some of my rooms and conversations belong to this one thing, I'd like to group them together somehow." That is what spaces are for, they can group people and rooms, that means they are a tool to organise rooms and people by topic. When creating a space, you can add existing rooms, direct conversations and users to it. You can always add more rooms and people later and both rooms and people can be members of arbitrarily many spaces, so you can group them however you like.
-{{ :services:matrix:community.png?1000 |}}
-After starting a community, you can add people and rooms via sidebars, just like adding users to a room.
+Unfortunately which spaces exist on the server is currently **not** searchable, so you will need to be invited to join an existing space. This should become more comfortable soon™️.
-When you join a community it gets added to your community sidebar. When you left-click on its symbol, your list of direct message sessions and rooms get filtered to members of your community and rooms belonging to your community, left-clicking again reverts to the default. Right-clicking on the symbol gives you a context menu to get to the community page.
+Spaces are handled via the sidebar on the far left of your screen. It might look something like this.
-===== End-to-End-encryption =====
+{{ :services:matrix:spacessidebar.png | }}
-<note important>End-to-End-encryption is currently enabled by default for direct chats. This has technical reasons.</note>
+This shows the sidebar of an account with two spaces (with initials T and F). Clicking on either of them will narrow the list of direct conversations and rooms to only those that belong to that space. The button at the top will return you to the view where you see all your direct conversations and rooms you are a member of (the //Home screen//). The bottom at the bottom will create a new space.
-End-to-end encryption means that only the parties participating in a conversation are able to decrypt and read the messages that were send. Our server is not able to decrypt the messages that were sent, preventing third parties to read the messages.
+By default rooms that are part of a space are not shown in the list of rooms on the Home screen. If you want a room, that is part of a space, shown there you will need to either
+  - set it as a favourite via the three button menu when you hover over its name,
+  - right-click on the Home button and then on //Show all rooms//, or
+  - enable //Show all rooms in Home// in the Spaces section of the //Preferences//
+You can also just search for the name of the room in the search box above the list of all your rooms and conversations.
-<note warning>If you enable end-to-end encryption for a room it cannot be disabled anymore later. If you lose your keys, you will lose access to your encrypted messages. Please make a backup of your keys / generate a recovery key.</note>
+=== Public Spaces ===
-<note warning>When logging into a new device (a different browser, a new phone, your fridge), you will only get access to your already encrypted messages //after// verifying the new session. This is explained below (and most easily done if you use Element on your phone).</note>
+When you click to create a new space you will be greeted with a small window
-==== Upgrading encryption ====
-This step is necessary if you have used encryption in the past on your matrix.physik.fu-berlin.de account. If you have not used encryption previously, you can jump to the section [[services:matrix:start#setting_up_encryption_for_the_first_time | Setting up encryption for the first time ]]
+{{ :services:matrix:spacescreationdialog.png | }}
-If you have used encryption before you will notice a small popup on the left side of the screen, asking you to upgrade. Click on the "upgrade" button to start the upgrade. {{ :services:matrix:riot_e2e_upgrade_01.png?direct&800 |}} Next you will have to enter your ZEDAT-password… {{./riot-e2e-doku-pictures/riot_e2e_upgrade_02.png |}} and enter your recovery passphrase you set when you set up key backups for encryption. If you can not remember your passphrase you can use the recovery key if you have still saved it somewhere. Alternatively you can set up a new key recovery. Your previous encrypted messages will still be available if you are able to read them on the device you are using to perform the upgrade. {{./riot-e2e-doku-pictures/riot_e2e_upgrade_03.png |}}
+You can create public spaces (that - in the future - will be searchable like public rooms) and private spaces. Private spaces are for closed groups or just for your personal usage to organise rooms just the way you like.
-This concludes the upgrade. You can now on read how to verify users in //*Verify a user//, or use encrypted chats without verification.
+If you click to create a public space you will get this small window
-==== Setting up encryption for the first time ====
+{{ :services:matrix:spacespubliccreationdialog.png | }}
-When you log in to Element, it will ask you to set up encryption recovery. This step will make sure that you can share encrypted messages across all your devices and different sessions. If you do not wish to use encryption you can skip this step. However as encryption will be used by default we highly recommend setting up encryption.
+where you can set a name and description for the space. This dialog is the same when creating a private space.
-To setup encryption recovery you have to choose a secure passphrase.
+Afterwards you will be offered to create rooms for that space
-{{ :services:matrix:riot_e2e_setup_01.png |}}
+{{ :services:matrix:spacesroomcreation.png | }}
-**Optional** By default the server backs up your encryption keys, so you can recover your encrypted messages if you loose access to all sessions that had access to them. You can choose for the keys not to be saved on the server. They can still be transmitted from one active session of yours to another.
+If you already have rooms that you want to add to the space and don't want to create new ones, you must delete the suggestions so that the **Continue** button changes to a **Skip for now** button.
-Additionally you can download a recovery key, which you can use if you forget or loose the passphrase.
+Afterwards you can add other people to your room either by copying an invite link or via the usual dialog to add people to a room.
-{{ :services:matrix:riot_e2e_setup_03.png |}}
+{{ :services:matrix:spacespublicinvite.png | }}
-==== Verification ====
+You can always add rooms and people to your space later.
-**This step is optional** **If you choose to not verify a user there will be a black shield displayed next to their user icon** {{ :services:matrix:riot_e2e_verification_icon_1.png |}}
+Finally you will land on the landing page of your space
-For end-to-end encryption to be really secure users have to verify they are talking to each other. To do this each user is verifying each their devices, and additionally verifies every user once. Every device another verified user verified themselves will be considered verified.
+{{ :services:matrix:spaceoverview.png | }}
-A user you did not verify will be displayed with a black shield next to their user icon: {{ :services:matrix:riot_e2e_verification_icon_1.png |}}
+Here you can add more rooms and people to your space or change its name and description and whether it is public or private (via the settings menu that you can reach via the gear symbol)
-A user you verified, but who did not verify all of their devices will be displayed with a red shield next to their user icon: {{ :services:matrix:riot_e2e_verification_icon_3.png |}}
+=== Private Spaces ===
-A user you verified and who verified all of their devices will be displayed with a red shield next to their user icon: {{ :services:matrix:riot_e2e_verification_icon_2.png |}}
+You can create private spaces for your groups or projects or just for yourself. That's the first question you will be asked when creatin a private space
-Example: Alice and Bob start a conversation in their logged in sessions. For the encryption to be secure they have to verify they are actually talking to each other. In Element this is done by comparing a list of emojis that are shown to both users. Alice requests a verification with Bob and they verify they get shown the same string of emojis. When Bob starts using a new session (e.g. using a different Browser/Device) he can use the session that was verified with Alice's session to also verify his new session. Alice's session automatically sees that Bob verified the new session and accepts it into the encrypted conversation.
+{{ :services:matrix:spacesprivatequestion.png | }}
-==== Verify a user ====
+If you press **Just me** here, you will be shown a list of all the rooms you are a member of and you can mark them to be added to your private space.
-For this step to make sense you have to be able to communicate with the other user in a way that makes sure you are actually talking to ****them****. For this we recommend video/audio-chat, or just sitting next to each other.
+if you press **Me and my teammates** you will be shown a dialog to invite people
-To verify a user you open a chat you share with the user and click their name in the user side bar.
+{{ :services:matrix:spacesteammatesinvite.png | }}
-{{ :services:matrix:riot_e2e_verify_user_01.png?direct&800 |}}
+You //must// invite them via their usernames or skip this step for now, since for our Matrix instance users will not be able to join via app.element.io
-Click on the verify link in the sidebar…
+Afterwards you will get the same room creation dialog as for public spaces discussed above, where you need to remove the suggested room names if you don't want to create new rooms to skip that step.
-{{ :services:matrix:riot_e2e_verify_user_02.png?direct&800 |}}
-and click on the "Start Verification" button.
-{{ :services:matrix:riot_e2e_verify_user_03.png?direct&800 |}}
-The user you want to verify will see the request as a popup on the left and in the chat.
-{{ :services:matrix:riot_e2e_verify_user_04.png |}} {{./riot-e2e-doku-pictures/riot_e2e_verify_user_05.png |}}
-You will then be presented with the verification options. Currently the only option is comparing a string of emojis. When both users have agreed on a verification method the verification process begins.
-If the user you are verifying with is shown the same string of emojis as you are, you can both click on "They match" to complete the verification.
-{{ :services:matrix:riot_e2e_verify_user_08.png |}}
-==== Verify a session ====
-To access your encryption history and for other users to verify you it is necessary to verify a new session. To verify a session you can either confirm a new session from an existing session or enter your recovery passphrase.
-When logging in with a new device you will get prompted to verify it.
-{{ :services:matrix:riot_e2e_verify_session_01.png?direct&800 |}}
-If you are logged into another session there will be a popup asking you to verify the new session:
-{{ :services:matrix:riot_e2e_verify_session_02.png?direct&800 |}}
-Click on the green "Verify" button in the popup and an explaining popup will appear.
-{{ :services:matrix:riot_e2e_verify_session_03.png |}}
-Select to continue and you will be asked for a verification method. Currently the only option is to compare a sting of emojis.
-{{ :services:matrix:riot_e2e_verify_session_04.png |}}
-Compare the emojis in the two sessions.
-{{ :services:matrix:riot_e2e_verify_session_05.png |}}
-{{ :services:matrix:riot_e2e_verify_session_06.png |}}
-Confirm the emojis match on both devices to complete verifying the session.
-Alternatively you can select to verify a session by using your recovery passphrase:
-{{ :services:matrix:riot_e2e_verify_session_09.png?direct&800 |}}
-==== Deleting a session ====
-If you have old unverified sessions that you don't have access to anymore, it is best to delete them so that other users don't see you as unverified.
-To find out if you have unverified sessions left, enter a chat in which you participate and find your name in the user sidebar on the left. If you have unverified sessions, there will be a red shield icon on your user icon.
-{{ :services:matrix:riot_e2e_delete_session_01-1.png?direct&800 |}}
-If you have unverified sessions, click on your name in the sidebar. This will show you a list of your sessions and which of them are unverified.
-{{ :services:matrix:riot_e2e_delete_session_01-2.png?direct&800 |}}
-Click on each of the unverified sessions which you can not access anymore and note down their session-ID. (In the picture below it is //VBPCSWTETS//)
-{{ :services:matrix:riot_e2e_delete_session_01-3.png |}}
-To delete the session you noted down, click on your Name in the top left corner and select the settings.
-{{ :services:matrix:riot_e2e_delete_session_02.png?direct&800 |}}
-In the settings menu select the section "Security & Privacy"
-{{ :services:matrix:riot_e2e_delete_session_03.png?direct&800 |}}
-In the "Security & Privacy" setting select all the session you want to delete and click on "Delete sessions"
-{{ :services:matrix:riot_e2e_delete_session_04.png?direct&800 |}}
+If you later decide you want to share your private space with other people, you can always do that and invite people to it. Since the menu to add rooms to spaces is much nicer for personal use private rooms, this is the recommended way to create private spaces and to later invite more users to it instead of going through the general private space creation.
 ===== Usage tips =====
@@ Line 314: / Line 234: @@
   * You can reply to messages, quoting them thereby. Use the context menu when hovering over a message.
   * You can react to messages. Use the smilie context menu when hovering over a message.
-  * You can add a [[services:jitsi:start|Jitsi]] widget using our Jitsi server to bind a fixed Jitsi room to your Matrix room via the Widget integration menu (the 2x2 squares on the upper right). Be advised, the other integrations besides Jitsi use external resources.
+  * You can add a [[services:jitsi:start|Jitsi]] widget using our Jitsi server to bind a fixed Jitsi room to your Matrix room via the video camera button on the far right of the message input box
+===== More Documentation =====
+  * [[services:matrix:encryption|How to guide for end-to-end encryption on Element]]