Matrix migration services

What a Matrix migration involves

A Matrix migration usually starts with one of three triggers: moving off Slack or Microsoft Teams, consolidating several chat tools into one, or changing homeserver software or hosting setup. Each trigger carries different constraints. Leaving a hosted tool often means users expect their existing channels, direct messages and file links to survive the move, while consolidation means deciding which tool's history and conventions win when two teams collide. A move between homeservers or hosting setups is mostly an infrastructure exercise, but it still touches identities and room data.

A migration differs from a fresh deployment in three ways. Users already have identities, and those identities must map cleanly to the new server name, so the server_name setting and any user ID scheme need to be settled before anyone is imported. Existing history raises a decision about what is moved, what is archived read-only and what is left behind. Users must also keep working during cutover, so the team has to plan for coexistence, usually with bridges or a defined freeze window, and confirm how clients and notifications behave while both systems run.

A migration can run in parallel with the implementation plan. Identity integration, federation policy, storage and backup design can proceed while the import tooling is tested against a copy of the source data. Sequencing matters, though: decisions about identifiers and history should be frozen before the import rehearsal starts, or the rehearsal will need repeating.

Short answer: many teams with strong Linux and PostgreSQL skills run the platform side in-house, and bring in a partner when the import rehearsal, cutover plan and user onboarding must be delivered on a fixed timeline. The deciding factors are your team's capacity during cutover, how much source history you must preserve, and whether your identity provider and bridge choices are already settled. Ask any partner to state in writing which migration steps they own, which they support and what your staff must do.

What the migration work includes

Each work package below has a named deliverable the client receives. Confirm the source tool's export capabilities and licensing terms for your platform before fixing the scope.

Source assessment and data inventory

Inventory channels, direct messages, users, guests, attachments, integrations and retention settings in the current tool, and confirm what its export can produce for your plan and license. Matrix plans depend on these volumes and owners. Deliverable: a migration plan and data inventory that lists volumes, data owners and any data that cannot leave the source system.

Identity and room mapping

Build mapping files that tie each source account to a Matrix user ID on your server name, and each source channel or group to a Matrix room or space with its membership and power levels. Duplicate display names, departed staff and shared accounts need explicit rules. Deliverable: identity and room mapping files plus a reviewed exception list.

History import or archive decisions

Decide room by room whether history is imported into Matrix, kept in a read-only archive, or dropped. Import adds load to the homeserver and needs a tested converter, while an archive keeps retained messages searchable under your retention policy. Deliverable: a retention decision register, an archive of retained history and a test migration report on sample rooms.

Coexistence and bridge setup

When teams move in stages, a bridge can relay rooms between the old tool and Matrix during the transition. Confirm that the bridge supports your source platform, which data it copies, where message content is stored, and how it handles edits and deletions. Deliverable: bridge configuration, a data handling note and a test report on sample rooms.

User onboarding and training

Prepare account activation steps, client installation guides for the chosen Matrix clients, key backup and device verification instructions, and short sessions for room owners and administrators. Users who never set up key recovery can lose access to encrypted history, so this must happen before cutover. Deliverable: onboarding guides, training materials and a support FAQ.

Cutover runbook, rollback and decommissioning

Write the cutover runbook with freeze windows, a final data sync, client and DNS changes, and go or no-go checks. Define the rollback point before cutover, because Synapse upgrade notes warn that schema changes between releases can make rollback difficult. Decommissioning covers locking the old tool, exporting final data and shutting it down. Deliverable: runbook, rollback plan and decommissioning record.

What drives migration cost and duration

Each row names one factor that changes the effort of moving teams onto Matrix, why it matters and how to keep it under control, so you can compare scope before asking for a quote.

Driver	Why it changes cost or effort	How to reduce it
Users and rooms	Every account needs an identity mapping and every room needs a target room with the right members, so effort grows with both counts, and room counts often grow faster than user counts.	Inventory active rooms and users from the source tool first. Retire or archive inactive rooms and deactivated accounts before the migration scope is fixed.
History volume and age	Exporting, transforming and importing old messages and attachments takes time and storage, and very old history often uses formats the source tool no longer exports cleanly.	Limit history to an agreed window, such as recent active rooms, and keep older data in a read-only archive outside Matrix. Confirm what the source export actually contains.
Source type: SaaS or self-hosted	A commercial SaaS tool usually limits export options and depends on its admin export tooling and API rate limits. A self-hosted homeserver gives direct database access but needs its own version and schema knowledge.	Confirm export rights, formats and API limits with the source vendor or your administrators early. For self-hosted sources, document the version and database engine before planning.
Identity sources and ID mapping	Users may exist in several directories with different identifiers. Mapping them to stable Matrix IDs on your server_name is often the slowest decision, because duplicate or renamed accounts need manual review.	Agree one authoritative identity source early, such as your SSO provider, and decide the Matrix ID format before any import. Plan how display names and departed users are handled.
Room structure and permissions	Spaces, nested channels, moderators, guest access and per-room encryption settings must be recreated. Each permission model that differs from the source adds design and testing work.	Simplify the room model before migration. Use a small set of room templates with fixed power levels, and document which permissions are recreated and which are dropped.
Federation during transition	If federation is enabled while users are still moving, you must define which external domains can join rooms, and this adds policy review and firewall testing. Keeping federation closed limits coexistence with outside contacts.	Decide the federation policy before cutover. Use a domain allowlist for partner organizations where needed, and confirm the listener and firewall settings with your security team.
Bridges during coexistence	Each bridge needs its own hosting, account mapping, testing and monitoring, and bridged messages create data flows that your data handling and retention rules must cover.	Limit bridges to the rooms and time window that need them, and set an end date for each bridge. Confirm which message content and metadata the bridge stores and for how long.
Compliance and retention on old data	Legal holds, retention schedules and records rules can require export in specific formats, verified deletion from the old tool, or a documented chain of custody. These obligations can add review steps to every phase.	Ask your compliance or legal team to define retention categories before scoping. Agree how old data will be retained, exported or deleted, and who signs off each step.
Single or multiple target environments	Running production, test and disaster recovery environments, or separate environments per business unit, multiplies configuration, testing and cutover work.	Start with one target environment and one pilot group. Add environments only when a documented requirement needs them, and keep configuration in version control to reduce repeated effort.

Migration phases and outputs

The sequence moves a chat estate onto Matrix through a tested pilot, a rehearsed history import, a documented cutover and a sealed archive of the source.

Audit the source and inventory what moves
Your team and DeployOpen list rooms or channels, users, admins, integrations, bots, retention rules, file attachments and compliance holds in the current chat tool. Output: an audit inventory that classifies each item as migrate, archive, bridge or retire. The phase is done when the business owners have signed off the inventory.
Design the target homeserver and identity
Decide the homeserver implementation, version line, PostgreSQL version, server_name, the domain used in user IDs, federation policy and how users sign in. Synapse releases since 1.143.0 require PostgreSQL 14 or newer, so the database baseline is set here. Output: an approved target design record covering hosting, identity integration and naming. Confirm the exact minimum versions against the upgrade notes for the release you choose.
Pilot the migration in a non-production environment
Stand up a non-production homeserver with the target design, load a representative sample of rooms, users and attachments from the audit, and test sign-in, federation settings, clients and any bridges. Output: a pilot report listing defects, workarounds and open decisions. The pilot is complete when the defect list has an owner and a fix or accepted risk for each item.
Rehearse history and room migration
Run full-scale import rehearsals of room history, membership, media and access settings against copies of production data, timing each run and recording where the process breaks. Decide how much history moves and how the old archive stays searchable. Output: a rehearsal report with the run sequence, error log and a go or no-go recommendation. Repeat until a run completes with no unresolved errors.
Onboard users and communicate the change
Prepare account provisioning through the chosen identity path, client installation guides, a rooms directory, a cutover calendar and support routes for questions during the move. Brief team leads on which rooms move and which stay in the old tool. Output: a communications pack and a provisioning test log showing every pilot group signs in on the target clients.
Cut over production with a rollback decision
Freeze writes in the source tool, run the final delta import, switch DNS or delegation to the new homeserver, and verify sign-in, messaging, federation and bridges against a checklist. Output: a signed cutover checklist and a rollback decision record. Schema changes between Synapse releases can make rollback difficult, so the record must name the point after which rollback is no longer planned.
Run coexistence then decommission the source
Keep the source read-only for a defined coexistence period, use bridges only where the audit marked them necessary, and track which teams still post in the old tool. Once owners confirm retention obligations are met, export a final archive, revoke integrations and shut the source down. Output: a final archive with a hash manifest and a decommissioning record signed by the data owner.

What stays in-house and what a partner handles

This table separates the Matrix migration work your teams usually keep from the technical work often outsourced, with the skills each part needs, so you can see where your own staff fit.

Work area	Usually kept in-house	Often handled by a partner	Skills each part needs
Room and history decisions	Deciding which Slack or Teams channels, rooms and message history matter, and what can be archived or left behind	Mapping the decisions into export filters and a list of what each script will move	Business ownership, records management, change management
User lists and approvals	Approving who gets an account on the new server and which external users are invited	Generating the user list from the identity source and checking it against approvals	Identity administration, HR data ownership, access policy
Source export and transformation	Confirming which exports are acceptable and reviewing sample output for accuracy	Writing and testing the export and transformation scripts for room, user and file data	Python scripting, API handling of the source platform, data validation
Synapse and PostgreSQL target build	Choosing the hosting location, approving the version and supplying infrastructure access	Building the Synapse homeserver and PostgreSQL target, with configuration matched to the migration plan	Synapse administration, PostgreSQL operations, Linux and container administration
Identity connector configuration	Providing the upstream identity provider, its client registration and the group rules that decide access	Configuring the SSO connection to the identity provider and testing sign-in for each user group	Identity administration, OpenID Connect or SAML configuration, directory knowledge
Rehearsal and cutover execution	Scheduling the cutover window, signing off rehearsal results and agreeing the rollback decision with business owners	Running the full rehearsal, executing the cutover steps and verifying the result in the target	Runbook execution, Synapse and PostgreSQL operations, incident handling
Internal communications and onboarding	Announcing the change, training managers and answering staff questions after cutover	Preparing client setup guides and support material for the migration	Change management, internal communications, end-user support
Admin role ownership after go-live	Owning the new admin role, approving configuration changes and deciding on bridge retention	Handing over runbooks and documenting the configuration and scripts used	Homeserver administration, governance of admin access, documentation

What goes wrong in Matrix migrations and how to prevent it

Most Matrix migration problems are decided before any data moves: how user IDs are formed, when the server name is fixed, and how the old tool is shut down. The cards below name each failure and the control that prevents it.

Identity mismatches with the directory

Matrix user IDs are built from a localpart and the server_name, so a directory account with a changed or inconsistent username will not map cleanly to its old identity. Before cutover, export the directory, decide the localpart rule, and check every mapping in a rehearsal so that people do not end up with duplicate or orphaned accounts.

Server name chosen late

The server_name is part of every user ID and room identifier, so changing it after users exist effectively creates a new set of identities. Fix the server_name in writing before the first account is created, confirm the delegation and port plan with your network team, and treat any later change as a new migration rather than a configuration edit.

Incomplete history and lost attachments

Exports from Slack, Teams or another chat tool often omit edited messages, threads, reactions or files that were stored outside the message store. Ask the source vendor and your admin what the export includes, sample attachments end to end, and reconcile message counts per channel against an independent export before signing off on history.

Rooms recreated with wrong permissions

Imported or rebuilt rooms can lose power levels, join rules, admin roles or membership, which leaves channels open to the wrong people or locked for the owners. Document the permission model of each source room, script room creation from that record, and verify membership and power levels for a sample of rooms in a production-sized rehearsal copy.

Users posting in the old tool

If the old chat tool stays writable after cutover, teams keep splitting conversations across two systems and the migrated history stops being the record. Set a frozen source window, make the old tool read-only at a stated time, post a notice in both systems, and confirm the change with workspace owners before the window opens.

No rollback path after schema changes

Synapse upgrade notes warn that rolling back can be difficult because database schema changes occur between releases. Take a verified PostgreSQL backup before each upgrade, rehearse the restore on a production-sized copy, and record the exact release and schema state you can return to, so a failed cutover does not depend on reversing schema changes.

Bridges left running past plan

Bridges used for coexistence during migration often keep relaying messages long after the planned end date, which keeps data flowing to a platform that should be retired. Set a dated decommission plan for each bridge, name the owner who turns it off, and remove its access to the source platform once the frozen window closes.

How the migration changes by starting point

Slack migrations depend on what your workspace owner can export, and bridge availability is the first thing to settle because matrix.org lists a Slack bridge. Confirm its current status with the bridge project before you plan around it.

Export: Confirm which export your Slack plan produces and whether private channels and direct messages are included.
Identity mapping: Map Slack members to Matrix user IDs on your server_name, and decide how deactivated Slack accounts are handled.
History: Decide whether past messages are imported into Matrix rooms or kept in Slack as a read-only archive.
Bridge: Confirm the bridge works with your Slack plan and your Synapse version before a pilot.
Cutover: Run a bridged period for a few channels, then move teams channel by channel.

What your organization needs to provide

Gaps in these inputs are the most common cause of schedule slips in a Matrix migration. Most of the list below sits with your organization, not with the implementation team, so confirm owners and dates before the plan is signed. Expect the migration to pause whenever one of these items is missing.

Start with access to the source tool. You need an administrator account on Slack, Microsoft Teams or the existing chat platform with export rights, so that rooms, channels, membership and message history can be extracted. Name a business owner for each room group, since owners decide which rooms move, which are archived and which are retired. For identity, identify the authoritative source (for example, your directory or HR system), the user attributes it holds and who can change them. Matrix SSO planning depends on these attributes being accurate before the first login.

Control of the target domain is equally important. Confirm who can change DNS records and issue or install TLS certificates for the homeserver name, and who approves those changes. Provide a target hosting environment with PostgreSQL and a Python version supported by the Synapse release you select. Check the Synapse upgrade notes for the current minimum versions rather than assuming them from older guidance. Decide early on history retention, including whether imported messages are kept, how long they are retained and whether any legal holds apply to the source data.

Finally, plan the people side. Provide a current user list with the groups that should receive access and a communication channel for onboarding announcements, login instructions and a support route. Name an owner for post-cutover administration: someone who will handle user lifecycle, room moderation requests, retention settings and upgrades after the project team leaves. Without this owner, the handover stalls and the migration is not complete in practice.

Frequently asked questions about Matrix migration

What drives the cost and effort of a Matrix migration?

The biggest drivers are the number of users and rooms, how much history you move, how many sources you migrate from, and how many identity, client and bridge integrations are in scope. Cost splits into one-time work (scoping, data export and mapping, import tooling, cutover, user onboarding) and recurring work (hosting, PostgreSQL, media storage, upgrades and support). Ask any partner for a quote that itemizes these components and states which sources and volumes it assumes. Your own internal time for stakeholder decisions and user communication is a real cost even when it is not invoiced.

Can our own team migrate to Matrix without a partner?

Often yes, if you have engineers who already run PostgreSQL and Linux services and someone who can own the Matrix homeserver after go-live. The harder parts are rarely the install. They are mapping users and rooms, deciding what history comes across, testing clients and integrations, and running upgrades on a schedule. Before deciding, check your team's capacity for upgrades, since Synapse releases are frequent and need testing. A fixed-scope partner engagement can cover the migration while your team takes over operations.

How is chat history handled, and what cannot be carried over?

History handling is a decision, not a default. Some teams import message history from the source tool, others keep the old tool read-only for an archive period, and others start fresh in Matrix. Imported history depends on what the source tool exports and what Matrix rooms can represent, so attachments, reactions, threads, edits, deleted messages and permissions may not map one to one. Confirm the export format and fidelity with the source vendor and test the import against a sample room before committing to a plan.

Do bridges make a Matrix migration easier?

Bridges help during coexistence, when some teams are on Matrix and others are still on Slack, Teams or another tool. They connect rooms across platforms so people can keep talking while onboarding is staged. They do not move history by themselves, and they add components to run, monitor and secure, along with questions about where message data is stored and who can see it. Matrix.org lists bridges for several platforms, but coverage, feature parity and maintenance status differ, so confirm each bridge's status and limits in your environment before relying on it.

How are user identities mapped from the old system to Matrix?

Each person needs a stable Matrix user ID based on your server_name, linked to the identity your organization already trusts. In practice, you match accounts from the source tool to employee records by a reliable attribute such as a verified work email or an identity provider subject, then provision Matrix users through single sign-on. Handle leavers, duplicate accounts and shared or bot accounts explicitly. Decide whether user IDs or display names carry history attribution, since this affects how imported messages appear.

What must our organization provide before a migration starts?

You will typically need to provide named decision owners, access to the source tool with export rights, a current list of users and channels with their memberships, the identity provider you will use for sign-in, DNS and TLS certificate control for the homeserver domain, hosting capacity in your own cloud or data center, and a retention and confidentiality policy that says what history may be moved. Also provide a test group of users and a rollout communication plan. Confirm exact requirements with the partner against your written scope.

Is a rollback possible after cutover?

Rollback is harder than it looks. Synapse upgrade notes warn that rolling back can be difficult because database schema changes between releases may not reverse cleanly, so the same caution applies after a cutover that includes a migrated database. Plan for a rollback window with a tested database backup taken immediately before cutover, keep the source tool available read-only, and agree in advance on what data written to Matrix after cutover would be lost or re-exported. Test the restore procedure in a staging environment before you rely on it.

What happens to the old chat tool after migration?

Most organizations keep the old tool read-only for a defined period so staff can look up history and so the archive remains available for legal or audit needs. After that period, you decide whether to export a final archive, delete data, or keep a long-term copy in a system you control. These decisions depend on your retention obligations and on contract terms with the source vendor, so confirm them with your legal and compliance teams and the vendor before shutdown.

How DeployOpen works on this

DeployOpen plans, builds, documents and supports Matrix migrations inside infrastructure you control, from the first decision about source platform and history to the hand-over of a working homeserver and onboarded teams. Engagements are fixed-scope, with scope and deliverables agreed in writing before work starts.

How we scope

Inventory the source chat tool, its rooms, users, retention settings and integrations before choosing a target design.
Record the homeserver choice, server_name, federation policy and identity approach in the written scope.
Agree in writing which history is migrated, which is archived, and which bridges run during coexistence.

How we build

Deploy the chosen Matrix homeserver, database, media storage and clients in your cloud accounts, data centers or air-gapped network.
Connect identity through your chosen single sign-on approach and test account provisioning before any user is moved.
Run a rehearsal migration of sample rooms and users, then verify message counts, membership, media and access controls.

How we hand over

Deliver runbooks for onboarding, room migration, bridge operation, backup and restore, and cutover steps.
Document configuration, upgrade assumptions and the database and Python versions your release requires.
Train administrators and agree who owns each operational task after the written scope closes.

How we support

Offer ongoing support, upgrades and testing as a retainer after cutover, covering homeserver releases and dependencies.
Keep a post-cutover review of user onboarding issues, bridge health and any late-discovered history requests.
Confirm with us during scoping which upgrade and support terms apply, so rollback limits are understood before go-live.

Matrix migration