Recently, some friends and I decided to switch servers for a more powerful one. We also decided to move away from our old domain, which got more expensive to renew, and use a new one.

For some services, switching domains has close to no implications. But for a self-hosted Matrix instance, it means re-creating the entire homeserver, as there is no way to just change the domain name.

I decided to write this post to help people who may have to move to another homeserver.

Hosting a new homeserver

With the switch, I decided to use my own nemophila.me domain.

Having a different domain means you can’t just go and copy your previous installation, do some stuff, and voila. You have to go back to the beginning.

I won’t be going into much details, but we decided to host multiple homeservers on the same machine (which is beefier and can handle several Synapse instances).

For installation of your new homeserver, just follow Synapse’s latest guide.

Joining your old rooms and spaces

I’ll assume you’ve set up your new homeserver, and created your new user.

Do note some spaces and rooms could be invite only, and you may need to ask someone to invite you back into them.

Please read the section until the end.

Doing it manually

You could manually join all of your spaces, rooms, and DMs.

You’ll have to use your old account to propagate your old permissions to the new account, so that you keep the same privileges.

If you’re going fast, you may struggle with rate limits. See below.

Using EMS tool

There’s the EMS Matrix migration tool, which helps a lot. It will need to login to both users however, if you’re okay with this.

Everything is done locally, but I do not think the code of the tool is open sourced. Once logged, you’ll see the following before starting the migration:

I’d suggest keeping the options as they are.

The tool works … somewhat. It seems to struggle with spaces, and it will fail to join some rooms. It perfectly works for DMs (with a small twist, see Fixing up DMs). You will have some manual work for those failed rooms.

It will also most likely struggle with rate limits, even if you bump the delay in the tool’s advanced options.

Bumping rate limits

Rate limits may hinder your progress. You could wait… Or temporarily bypass them.

The following applies for small instances made for personal use. If your instance is semi-public or has many users… maybe don’t do this. It’s quite agressive of a change, and you should revert it once you’ve finished.

You can change the homeserver.yaml configuration to temporarily remove rate limiting on room invites and joins. This will help in avoiding M_LIMIT_EXCEEDED errors.

rc_joins:
  local:
    per_second: 999
    burst_count: 999
  remote:
    per_second: 999
    burst_count: 999
rc_joins_per_room:
  per_second: 999
  burst_count: 999
rc_invites:
  per_room:
    per_second: 999
    burst_count: 999
  per_user:
    per_second: 999
    burst_count: 999
  per_issuer:
    per_second: 999
    burst_count: 999

Don’t forget to revert it when done!

After the migration

I’ll assume you’ve either manually or semi-automatically joined all of your past spaces, rooms, and DMs.

Importing encryption keys

Every encrypted room will just be a wave of “Waiting for this message” or similar messages, related to your new account missing encryption keys.

On your old account, in “Security and Privacy”, you can export your keys.

Then, on your new account, in the same menu, you can import your keys. You’ll now be able to see all encrypted messages (with a warning next to them).

Don’t forget to also setup “Secure Backup” in the same menu.

Fixing up DMs

You’ll notice your DMs have become rooms on the new account, and have three users:

• your old account
• your new account
• the recipient

I’d suggest leaving the DM with your old account. The DM will still stay as a room. To fix this, take note of:

• the recipient’s account (@user:domain)
• the room ID (found in Room Settings > Advanced)

On a PC client, in any room, type /devtools. You should see the following menu:

Go in “Explore account data” then “m.direct”. You’ll see a JSON that should look like this:

{
  "type": "m.direct",
  "content": {
    "@user:domain": [
      "roomid"
    ],
    "@user2:domain2": [
      "roomid2"
    ]
  }
}

Just edit the JSON to insert all of your DMs. This will fix their display.

Leaving rooms

You could also leave rooms on your old account.

In my case, I chose to do it progressively since my old domain will expire, and therefore this user will just become a ghost. If your old homeserver is still active, you could keep the user in these rooms. Your choice!

Clearing sessions (EMS tool)

If you’ve used the EMS migration tool, as I said, the tool logs into your accounts. It means that it creates new sessions on those accounts.

I’d recommend signing out of those sessions, even if your homeserver may clean them at some point (depending on configuration).

The disadvantages

Rooms with limited history

Rooms can be configured with the following history visibility:

• Anyone
• Members only (since the point in time of selecting this option)
• Members only (since they were invited)
• Members only (since they joined)

If a room is setup with the last two options… You’re out of luck.

I personally chose to export those rooms with Element’s integrated export tool, that you can find in the sidebar.

Spaces and rooms with limited access

You may have to ask someone with privileges to invite you to some spaces and rooms.