Migrate From EMS to Self-Hosted
For support on Synapse or matrix-media-repo, ask in the Matrix rooms #synapse:matrix.org and #mediarepo:t2bot.io. For support on bridges, see the bridge documentation for each bridge's support channel.
- It is impossible to change the domain of any Matrix server. Therefore if your EMS server is not using Custom DNS (i.e. your Matrix IDs are
@someone:hostname.ems.host), unfortunately it is not possible to import your export to your own or another environment.
- You can run an export with this domain in a local environment if you set up your own DNS and self-signed certificates. But you will not be able to federate with the public Matrix federation.
- Do not cancel your EMS server until you have downloaded your export and verified its content. Canceling your server will erase your data.
- You will experience some downtime as your server will be stopped while the export is running. The EMS export tool will estimate the actual downtime when initiated.
- Ensure all your users have key backup configured and working before starting the export and migration. All clients need to log out and in again after the migration. See the Cross Signing section for more information about key backup.
- It is impossible to read encrypted messages or media from the export. Encrypted data in Matrix can only be decrypted by the user in their client when they have the required decryption keys.
- Go to https://ems.element.io/user/hosting#/exports
- Select the server you want to export from in the drop-down box, then click
- Wait for the export of your config, database, and media to complete
- Once all exports have completed, download all files provided
For all components, you must install the same version as your EMS server is running. Version information is provided in the
hostname-config.md file. If a newer version is available, once the import is completed and verified, follow the official upgrade documentation for each component to upgrade.
All required configuration values are provided in the
- Following official documentation, install and configure
- When generating your Synapse configuration file, you MUST use the same domain as your EMS server
- Do not start Synapse yet
- In the Synapse config file (usually
- pepper. If you do not do this, you have to reset all passwords
- Signing key. This is stored in a file. See this config file option for path. Alternatively, add the public key for your EMS hosted server to
old_signing_keys. If your EMS server is still running, you can find your public signing key at https://yourHostname.ems.host/_matrix/key/v2/server
- Import the Synapse database
- Create a new database per the Synapse PostgreSQL documentation
- Or, if your Synapse database is not empty, empty it
WARNING - THIS WILL IMMEDIATELY AND IRRECOVERABLY DELETE DATA, PLEASE TAKE CARE. WE ACCEPT NO RESPONSIBILITY IF YOU DELETE THE WRONG DATABASE OR DATA
Connect to the database with
psql, then run the following queries:
Disconnect from the database
DO $$ DECLARE r RECORD; BEGIN FOR r IN (SELECT tablename FROM pg_tables WHERE schemaname = current_schema()) LOOP EXECUTE 'DROP TABLE ' || quote_ident(r.tablename) || ' CASCADE'; END LOOP; END $$; DROP sequence cache_invalidation_stream_seq; DROP sequence state_group_id_seq; DROP sequence user_id_seq;
- Extract the database dump
- Import the database dump
pg_restore \ --username USERNAME \ --host HOSTNAME \ --dbname DATABASE_NAME \ --no-owner \ /path/to/id-emsHostname-synapse-database.dir/
- Verify that sequence was set correctly. Connect to the database and run the query
SELECT * FROM state_group_id_seq;
last_valueshould be greater than 1
- Import media according to documentation here
- Start Synapse and ensure everything is working as expected
- Optionally, install Element Web or use another Matrix client
- Optionally, install the sliding-sync proxy. This is required for Element X
- Note, we do not provide an export of the Sliding Sync database as this would not provide any value. As you need to log out and back in from Element X after the migration and in doing so your Sliding Sync proxy needs to re-sync each user. All your data is already included in the Synapse database
If you have any bridges, please see the documentation for each bridge
Discord | Hookshot | IRC | Signal | Slack | Telegram | Whatsapp
- The process for importing the bridge databases is the same as with Synapse
- Cancel your EMS server. See this FAQ document for instructions. Note, this cannot be undone and all your data will be lost. Ensure your imported server is working as expected before doing this