Migration of a Matrix account

Aus Volla Wiki

Migration of a Matrix Account from a Public Server to a Self-Hosted Instance

Migrating a Matrix account from a public server (e.g., matrix.org) to a self-hosted Matrix instance (e.g., using Synapse as a homeserver) is possible but requires careful planning due to the decentralized and secure nature of the system. Errors may lead to loss of access to existing chats or encryption keys. This guide outlines the steps to successfully migrate an account.

The author assumes no liability for this guide. Suggestions for improvement are warmly welcomed.

Prerequisites

  • An existing Matrix account on a public server (e.g., @user:matrix.org).
  • A fully configured self-hosted Matrix instance (e.g., with Synapse, nginx, PostgreSQL, and Let's Encrypt).
  • Access to a Matrix client, such as Element.
  • Basic server administration knowledge (e.g., SSH, configuration files).
  • Backup of the encryption keys from the old account (for end-to-end encryption).
  • Optional: Access to exported data from the old account, if supported by the public server (e.g., via Element Matrix Services).

Step-by-Step Guide

1. Setting Up Your Own Matrix Instance

Before starting the migration, ensure your self-hosted Matrix instance is operational. Follow these steps:

  1. Install and configure a Matrix homeserver (e.g., Synapse) on your server.
  2. Ensure federation is enabled and verify the configuration using the Matrix Federation Tester.
  3. Create a new user account on your instance with the command:
register_new_matrix_user -c /etc/matrix-synapse/homeserver.yaml http://localhost:8008
 Specify a username (localpart), password, and optionally admin privileges.

2. Preparing the Old Account

  1. Log in to your old account using a Matrix client like Element.
  2. Export the encryption keys for end-to-end encrypted rooms:
 ** In Element: Go to Settings > Security & Privacy > Encryption > Export Keys.
 ** Save the keys securely, as they are required to access encrypted chats.
  1. Note all rooms your old account is a member of, as these need to be migrated manually or automatically.

3. Migrating the Account

Migration can be done manually or with a tool. This guide describes the migration tool provided by Element Matrix Services, which simplifies the process.

  1. Create a New Account: Log in to your self-hosted instance with the new account (e.g., @user:mydomain.com).
  2. Log Out of the Old Account: Sign out of the old account in all apps.
  3. Use the Migration Tool:
 ** Visit the Element Matrix Services Migration Tool.
 ** Log in with both your old and new accounts.
 ** The tool automatically invites the new account to all rooms the old account was a member of.
 ** Optional: Enable the option for the old account to leave rooms once the new account has joined.
 ** Migrate metadata such as display name and avatar, if desired.
 ** Note: This is an experimental feature (Labs feature) and should be used with caution.
  1. Import Encryption Keys:
 ** In Element: Go to Settings > Security & Privacy > Encryption > Import Keys.
 ** Upload the previously exported keys to restore access to encrypted chats.

4. Verifying the Migration

  1. Check if the new account is in all desired rooms.
  2. Test communication in public and private rooms.
  3. Ensure encrypted chats are accessible using the imported keys.
  4. Optional: Deactivate the old account on the public server to avoid confusion (e.g., by deletion or deactivation, if supported by the server).

5. Post-Migration Steps

  1. Inform your contacts about your new Matrix ID (@user:mydomain.com).
  2. Verify server configuration (e.g., TLS certificates with SSL Labs) and federation.
  3. Regularly back up your Matrix instance’s database (e.g., PostgreSQL backups).

Important Notes

  • Security: Ensure your instance is properly configured with TLS certificates (e.g., Let's Encrypt) and a secure firewall (e.g., ufw).
  • Encryption: Without exported keys, encrypted chats may be lost. Back them up before migration.
  • Federation: The new instance must be properly federated to communicate with other Matrix servers.<ref name="web21" />
  • Manual Migration: If the migration tool is unavailable, you can manually invite the new account to all rooms and have the old account leave afterward. This is more time-consuming.
  • Risks: Migration is a sensitive process. Errors may render the old account unusable. Always create backups.

Additional Resources

Abgerufen von „http://wiki.volla.online/index.php?title=Migration_of_a_Matrix_account&oldid=427“