This article is a work in progress, don't trust it's contents, yet

Migrate to ETH ID's Matrix service

Except for the Computer Vision Lab (CVL) all D-ITET institutes and groups have to migrate away from D-ITET ISG's Matrix service to ETH ID's Matrix service. This article explains how to do this.
Read this manual completely before starting your migration. When you start your migration, follow to the order of the migration steps outlined here.

Terms, abbreviations and main steps

The terms and abbreviations described in this paragraph will be used throughout the remainder of this document.

• The homeserver is the Matrix service on which an account or room was initially created. The following four homeservers are distinguished:

  Homeserver	Managed by	Available to	Type
  matrix.ee.ethz.ch	D-ITET ISG	staff	old
  matrix-stud.ee.ethz.ch	D-ITET ISG	students	old
  staffchat.ethz.ch	ETH ID	staff	new
  studentchat.ethz.ch	ETH ID	students	new

• The D-ITET homeserver will be referred to as the old homeserver, the ETH ID homeserver as the new homeserver.
  Make sure you know which is your old and new homeserver based on your ETH affiliation.
  

• The credentials you use to login on both old and new homeservers are always your ETH login and ETH password

• At first login on a homeserver, your account is created. It stores your settings on the homeserver.

  Your account on the new homeserver is referred to as your new account, your account on the old homeserver as your old account.

• Rooms on the old homeserver you have the role Admin in are referred to as Your rooms

• All other rooms in which your role is Default are referred to as rooms you joined or rooms you're a member of

• Public rooms can be joined by anyone, private rooms can only be joined after receiving an invite

• 1:1 people chats are identical to rooms from a technical viewpoint and not distinguished here. All actions referring to rooms have to be applied to 1:1 people chats as well. Certain actions don't have a user interface (as opposed to rooms) and need to be completed through the developer tools.

You might want to do a simple migration or a more complex one, depending on your personal preference. Make sure you understand the necessary preparation and decide which steps of the migration you will do and which steps you'll leave out.

Examples of migrations with varying complexity

The first step of any type of migration is to set up your new account.

Afterwards you could passively wait until your new account gets invites to rooms and be done with the migration. If you want to invest more time you can actively start to join the rooms your old account is a member of and ask for invites for your new account.

If you want to be able to decrypt the chat history of a room which originated on the old homeserver with your new account, you'll have to transfer your E2E keys.

If you are a room admin, you could simply set up a successor room on the new homeserver and let people know how to join it, provided the chat history of the original room is irrelevant.

Or if you want to retain your room's chat history you can set up your new account as room admin and proactively invite the new accounts of existing (old) room members

Preparation

For the migration to go smoothly there are mandatory steps you need to do. The optional steps are for your convenience and not strictly necessary, but helpful.

Mandatory preparation

Prepare your new account

1. Read the official documentation of ETH ID's Matrix service

2. Log in on your new homeserver (see next step for how to do this). This step creates your account and allows others to invite you to rooms with your new account.

3. Read the official documentation on how to set up your new account on ETH ID's Matrix service

4. Set up your new account as outlined in the official documentation

Verify security settings and sessions of your old account

As described in ETH IDs official documentation under Self-Verification:

• Do the self-verification of sessions you have on different devices
• Verify any cleanup your sessions

Optional preparation

For the following migration steps it's convenient to open a browser window logged into your old and new account each, to be able to switch back and forth between them.

Visually distinguish your old and new account

• To be able to visually distinguish your old and new accounts, you might want to upload different profile pictures for the time of the migration

• It might also be helpful to change the display name of your accounts for the same purpose (See screenshots under How to invite an account for examples)

Add homeservers to enable room search

A foreign homeserver can be added to an account to enable search for public rooms on the foreign homeserver. Do the listed steps for both your old and new account. Specifically, while logged into your new account, add the old homeserver. While logged into your old account, add the new homeserver.

1. In the column listing your rooms, klick on the plus symbol [+] to the right of the title Rooms:
   

2. From the popup menu select Explore public rooms:
   

3. Klick on the arrowhead pointing downwards [⋁] next to Matrix rooms [<homeserver>]:
   

4. In the popup menu select Add a new server:
   

5. Enter the new homeserver if you're working with your old account, enter the old homeserver if you're working with your new account.
   The homeserver in the screenshot staffchat.ethz.ch is an example if you're a staff member and are logged into your old account. Make sure you enter the foreign homeserver matching your ETH affiliation here.
   

6. Klick on Add

This enables to search for rooms you might only know part of the room's name. Another way to access rooms is by using their name or ID.

Enable chat history decryption for your new account

In case you're not interested in any room's chat history, skip ahead to the next step. Be aware by skipping this step, previous chat history will never be available to your new account.

For your new account to be able to read the chat history of the freshly joined rooms, the end to end (E2E) room keys have to be exported from your old account and imported with your new account.
The E2E keys of a room are rotated every 7 days or after 100 messages so this step needs to be done quickly after joining a room with your new account.

Export E2E keys from your old account

In your old account:

1. Klick on your display name in the top left area to open a popup menu containing the account settings:
   

2. Select Security & Privacy:
   

3. Under Encryption → Secure Backup klick on Restore from Backup to make sure all your room keys are loaded in your session:
   
   

4. Under Encryption → Cryptography klick on Export E2E room keys to save the room keys to a file:
   

Import E2E keys to your new account

In your new account:

1. As with the export step before, go to Settings → Security & Privacy → Encryption → Cryptography

2. Klick on Import E2E room keys to load the room keys from the file you previously saved

Join rooms with your new account

This might be as simple as accepting invites to rooms. For rooms you haven't gotten an invite, yet, you can check their settings and try to join them yourself. If rooms are private, you'll have to ask for an invite. Whenever you successfully joined a room with your new account, leave it with your old account.

Accept invites with your new account

1. Check if your new account already received invites to rooms your old account has joined:
   

2. Accept the invites for those rooms you want to join:
   

Check uninvited rooms' settings

With your old account, repeat the following steps for each room your new account hasn't been invited to, yet. The example room used here is called Showroom. The goal here is to figure out the rooms privacy setting and its address or ID.

1. Hover your mouse over a room's name in the room list

2. Klick on the triple dots [···] when they appear

3. Select Settings in the popup menu:
   

4. Check the room's access settings under Security & Privacy → Who can access this room?
   

5. Note the room's address or ID from the last part of the room's URL, beginning with either a hash [#] or an exclamation mark [!]:

   • #<room address>:<rooms homeserver>

   • !<room id>:<rooms homeserver>

   Alternatively you can find a room's address in its settings under General → Room Addresses → Published Addresses → Main Address. Our example room's address is #showroom_localaddress:matrix.ee.ethz.ch:
   
   And it's ID under Advanced → Room information:
   

Depending on the setting, your next step is either to join a public room or ask for an invite if it's a private room.

Join public rooms with your new account

This is possible if a room is public, i.e. it's access setting is Anyone who knows the room's link, apart from guests or Anyone who knows the room's link, including guests:
→ try to join these rooms with your new account by entering each room's URL in your browser's URL field:

• https://<new homeserver>/_matrix/client/#/room/#<room address>:<rooms homeserver>

• https://<new homeserver>/_matrix/client/#/room/!<room id>:<rooms homeserver>

Alternatively you can search for a public room after you added the room's homeserver and join it directly.

Ask for an invite to a private room for your new account

This can be done in private rooms where your old account has been previously invited to, i.e. the room's access setting is Only people who have been invited:
→ With your old account enter the room you want your new account to join and ask the room admins to invite your new account:
Please invite my account @<ETH username>:<new homeserver> due to the Matrix migration from D-ITET to ETH ID.

Admins are labelled as such in the room members list. In case the list is too long, look for a room admin in the room's settings under Roles & Permissions.

Leave rooms with your old account

After successfully joining a room with your new account, leave the room with your old account. This step is important, as deletion of a room from the old homeserver is only possible when there are no more members with local accounts:

1. Open the popup menu containing the room's settings again

2. Select Leave Room

Your old account can only be deleted from the old homeserver after it left all rooms, so make sure you see no more 1:1 people chats listed under People or rooms listed under Rooms.

Establish your rooms on the new homeserver

You have the choice of recreating your rooms from scratch on the new homeserver and invite room members again with their new accounts or allow anyone to join by themselves. This is an easy way to clean up the chat history and memberships. If you set up such a successor room on the new homeserver, post it's address in your old room so current room members are able to find and join it with their new accounts.
If you want to keep the chat history of a room, follow the steps below to synchronize your rooms to the new homeserver.

Exception: Local rooms

The exception are local rooms set up to be accessible only on their homeserver. They cannot be synchronized to another homeserver. Such rooms will have to be re-created on the new homeserver, the chat history will be lost.
Rooms with such a setup show This room is not accessible by remote Matrix servers under Room Settings → Advanced → Room information:

If you invite an account on the new homeserver to a local room on the old homeserver, the invite will fail.

Set up your new account as admin

Elevating an invited user to the role Admin can be done with a userinterface for rooms. The steps for 1:1 people chats have to be done with the developer tools.

Invite your new account

With your old account, repeat the following steps for each of your rooms/1:1 people chats:

1. Invite your new account with your old account

2. Have your new account accept the invite. Verify this happened in the chat history:
   

Elevate your new account to room admin in a room

1. With your old account, grant your new account the role Admin by klicking on its profile picture appearing in the chat stating its joining.

2. Grant your new account the role Admin:
   

3. On the appearing warning dialogue, klick Continue

Elevate your new account to room admin in a 1:1 people chat

1. Open the popup menu containing the room's settings

2. Klick on Advanced

3. Klick on Open Devtools

4. Klick on Explore Room State

5. Klick on m.room.power_levels

6. In the appearing window, scroll down and klick on Edit

7. In the section "users": {...}, put the line "@<ETH username>:<new homeserver>":100, between the two already listed users

8. Klick on Send

9. Get back to the initial settings window by klicking on the [X] in the top right corner of the current window

10. Leave the settings window

Verify the new role

1. Verify the role change is visible in the room's chat history:
   

Replace room members with their new accounts

Depending on your rooms setting, people either need your invite to join it or can join freely. If an invite is necessary, repeat the following steps with your new account for each of your rooms. If your room has other admins than yourself, coordinate these steps with them:

1. Invite members again with their new accounts.
   Some users might not have logged into their new account and cannot be invited yet.
   The Computer Vision Lab (CVL) won't migrate to the new homeserver and its members don't need to be invited with their new accounts.

2. After a successfully sending an invite to a new account, kick its corresponding old account out of your room to facilitate later deletion of the room from the old homeserver

Leave your rooms with your old account

With your old account, repeat the following steps for each of your rooms:

1. Verify your new account has the role Admin

2. Leave the room

Additonal how-tos

As inviting a new account and verifying the action is critical to the migration process, this seemingly simple task is explained here in detail.

How to invite an account to one of your rooms

The example room used here is called Showroom, the old account used in the example is called D-ITET Test User, the new account ETH ID Test User.

1. Right click on the room in the column listing all rooms

2. If the room has no members, yet, klick on the button Invite to this room:
   

3. Otherwise open the popup menu of a room containing Settings and select Invite People

4. Type the account you want to invite into the field left to the green button labelled Invite:
   

5. While you're typing, account suggestions appear in the lower part of the window. Select the account from the suggestions:
   

6. Klick on Invite

7. Verify the invite appeared in the room's chat history: