Since we launched the Element Server Suite (ESS) Community edition, we’ve been thrilled by the momentum. We are seeing a whole wave of new deployments and steadily growing engagement within the community. It’s clear that more people than ever want a robust, manageable way to host their own Matrix stack.
However, we’ve also heard a consistent question from those of you running older, "pre-ESS era" deployments: “How do I get my existing data into ESS without starting from scratch?”
Today, we are excited to answer that question. Available starting today, we are officially releasing an initial version of the ESS Migration Tool.
Why migrate to ESS?
For many long-time Matrix admins using Synapse, maintenance can be a manual burden including handling complex configuration, managing dependencies and keeping up with security updates.
By migrating to ESS, you leave that heavy lifting to Element’s ESS distribution. ESS is designed to make your life easier; once migrated, you can keep your system up-to-date, secure and packed with the latest Element features just by running a simple command. Furthermore you get all the components needed for a basic Element/Matrix stack out-of-the-box, curated and coordinated between each other, easy to deploy and maintain.
Introducing the ESS migration tool
The ESS migration tool is a dedicated tool designed to bridge the gap between your current Matrix environment and a modern ESS deployment. The tool automates the most tedious parts of moving to a Kubernetes-based ESS architecture:
- Configuration parsing: It takes your existing Synapse and Matrix Authentication Service (MAS) configuration files and parses them to discover secrets and linked files.
- Transformation: It converts those configurations into values files compatible with the ESS Helm chart.
- Kubernetes integration: It automatically generates the necessary Kubernetes Secrets and ConfigMaps.
The goal is minimal disruption. You can set up your new ESS environment and continue providing service to your users while immediately gaining access to powerful integrated features like Element Admin and Element Call.
A "breeze" for MAS migrations, too
Matrix Authentication Service (MAS) is the next generation of authentication and user management in Matrix. If you haven't moved your deployment to the MAS yet, ESS is your secret weapon. By migrating your environment to ESS Community first, you can utilise our built-in MAS migration tooling which automates the majority of the transition - check out the MAS migration guide. If you already have a MAS-enabled environment, no problem, you can still use the migration to get into ESS!
Getting started
The migration tool is available as a Python package and is licensed under AGPLv3. You can find basic instructions in the ESS Community repository. To help you through the process, we’ve prepared a comprehensive step-by-step migration guide as part of the tooling itself.
The roadmap: What’s next?
This first release is just the beginning. Our priority was to get this tooling into your hands as early as possible to gather feedback from the community. Over the coming months, we will be adding more functionality, including:
- Automated imports: Direct database and media file imports.
- Environment discovery: Automatic imports from existing Docker or Kubernetes contexts.
- System health: Integrated prerequisite checks to ensure a smooth transition.
- Expanded stack support: Migration support for Element Web, Matrix RTC/Livekit, and reverse-proxy configurations.
A note for commercial customers
While today’s announcement is a major milestone for our Community version, we haven't forgotten our Enterprise and Sovereign users. A top priority for our engineering team is facilitating a seamless "lift" from the ESS Classic stack to the modern ESS Pro environment.
The development to support customer migration paths is just around the corner and we are currently in the final stages of internal validation and will have more detailed news to share very soon. If you are an ESS Classic customer, you will be notified as soon as the Pro migration path is ready - and if you'd like to discuss your specific needs - please reach out to our support team.
Join the conversation
We want to hear about your migration experience. Your feedback directly shapes the future of this tool. If you run into any issues, let us know.
- Talk to us: Join the ESS Community Room.
- Report issues: Create a ticket in the ESS Community repository.
Start your migration today and experience the next generation of Matrix hosting!
