🧪 Testers wanted: Element Server Suite (ESS Community) for Cloudron

[andreasdueren]

Hi all,

The existing Synapse/Element packages on Cloudron work, but they predate Matrix 2.0: no Matrix Authentication Service, which means next-gen auth (Element X), and especially Element Call don't work properly. Instead of patching the old package I've built a new one that packages the full Element Server Suite (ESS Community) stack — the same components as Element's official Helm chart (element-hq/ess-helm), repackaged as a single Cloudron app.

What's included

One app, one container, the whole stack:

Component	Version	What it does
Synapse	1.157.1	Matrix homeserver (MSC4143 RTC transports enabled)
Matrix Authentication Service	1.21.0	Next-gen auth (OIDC-native, Element X compatible)
Element Web	1.12.24	Web client with embedded Element Call
Element Call (standalone SPA)	0.22.0	Guest-accessible call links
LiveKit SFU + lk-jwt	1.13.4 / 0.5.0	WebRTC media backend for calls
Element Admin	0.1.12	Admin UI (users, rooms)
Hookshot	7.4.3	Webhooks/bridges (optional)

Cloudron integration: SSO via the Cloudron OIDC addon → MAS → Synapse. Your Cloudron users log in with their normal accounts, including on Element X mobile. PostgreSQL via the Cloudron addon, well-known files served automatically, all configs regenerated from Cloudron env on every start.

What works today (v0.3.8)

• Login via Cloudron SSO on Element Web and Element X (iOS tested)
• Messaging, media, federation with other Matrix servers
• Element Call between users on your server (desktop confirmed, mobile in testing)
• Element Admin against MAS + Synapse admin APIs

Install

Install as a custom app via the version catalog:

App Store → Settings (gear icon) → Custom App Repository and enter https://git.due.ren/andreas/cloudron-ess/-/raw/main/CloudronVersions.json.

Repo: https://git.due.ren/andreas/cloudron-ess

The app asks for several locations at install time (all prefilled except the primary):

• Primary location = the account/auth domain — set this to e.g. account.example.com (this is where MAS lives; it must be primary because Cloudron's OIDC addon only registers callbacks on the primary domain)
• chat. → Element Web, matrix. → Synapse, mrtc. → RTC backend, admin.matrix. → Admin, call. → standalone Element Call

Current limitations / gotchas (please read before testing)

1. The apex domain alias. Matrix identity lives on your bare domain (@user:example.com), so https://example.com/.well-known/matrix/* must be served correctly. Right now the only way to do this is to add your bare domain as an alias on the ESS app — the app then serves the well-known files itself and redirects everything else to Element Web. That means the apex domain has to be parked on this app, which is far from ideal if you want to run something else there. Cloudron's built-in per-domain well-known support doesn't allow the custom JSON entries Matrix RTC needs (org.matrix.msc4143.rtc_foci), hence the request to the Cloudron team below.
2. Server name is permanent. The Matrix server name is baked in at first start. Changing domains later will brick your identity — the app refuses to start on a mismatch by design.
3. Federated calls require the other homeserver to also advertise an RTC transport (rtc_foci in its well-known). Calls with users on servers that haven't deployed Matrix RTC yet will show "Call is not supported" on their side.
4. Fresh installs only. No migration path yet from the existing Cloudron Synapse package (syn2mas migration is on the roadmap, untested).
5. Element X mobile calls — still shaking out well-known caching issues (log out/in after server updates if calls error out). Actively being worked on.
6. Resource usage: this is ~7 services in one container. Give it 2–4 GB memory.
7. Hookshot ships but is off by default; workers/redis scaling not implemented yet.

Request for the Cloudron team

@girish @nebulon The apex-domain situation (limitation #1) could be solved cleanly with a small platform feature: let an app declare custom well-known entries for its parent/apex domain — either in CloudronManifest.json or via an API the app can call — so Cloudron's nginx serves e.g. https://example.com/.well-known/matrix/{server,client} and /.well-known/element/element.json on the app's behalf, without the app claiming the whole apex as an alias.

Cloudron already serves some well-known content per domain, but there's no way to set the arbitrary JSON that Matrix needs today (e.g. the org.matrix.msc4143.rtc_foci transport entry that Element Call requires), and no way for a package to register it automatically. A wellKnown section in the manifest (updated on configure/restart) would benefit any protocol using apex-domain discovery — Matrix, WebFinger/Mastodon delegation, etc. Happy to write up a concrete proposal or beta-test an implementation with this package.

How you can help

• Install it on a test domain and report: SSO login, Element X login, 1:1 and group calls, federation with matrix.org
• Especially interested in: calls between two different ESS-package servers, iOS vs Android behavior, and apex/alias setups
• Issues → please reply here

Everything is rebuilt from upstream Element artifacts, config generation mirrors the official Helm chart, so upstream version bumps should be routine once this stabilizes. My plan is to eventually either implement the upstream ESS Community migration tool or build a custom script for future migrations from the legacy Cloudron matrix apps.

Thanks for testing!

[james]

Hello @andreasdueren
I just did a quick test.
Under the admin.matrix.$DOMAIN.$TLD is only the NGINX default page visible.
Is that how it should be? Should it not look like https://admin-beta.element.dev/login?

The documented way to get admin is false.

/app/code/mas/mas-cli --config /run/mas/config.yaml manage set-admin <username>
error: unrecognized subcommand 'set-admin'

  tip: some similar subcommands exist: 'demote-admin', 'promote-admin'

Usage: mas-cli manage [OPTIONS] <COMMAND>

For more information, try '--help'.

I took the tip command:

/app/code/mas/mas-cli --config /run/mas/config.yaml manage promote-admin james
2026-07-23T19:44:12.643967Z  INFO mas_cli::commands::manage:349 User promoted to admin user.id=01KY87V8HR9D8JC8FEAT5GD8Z1 user.username=james

Which looks like it worked.

[andreasdueren]

@james good catch, thanks for the feedback. Just pushed an update which fixes both.

[james]

Hello @andreasdueren
Small feedback.
Indeed, having the bare domain on the ESS app is a little confusing.
I now understand the request you have written for the well-known feature.

[humpty]

Correct me if I'm wrong as I'm trying to wrap my head around this:

• I cannot install this app alongside an existing matrix/element on the same domain
• The bare domain must be empty (no app installed)
• The primary location must be "account" (exact wording) and not something else e.g. comms.domain.com
• Running this app alongside existing matrix app on different domains BUT on the same CR is OKAY

[andreasdueren]

@humpty said:

Correct me if I'm wrong as I'm trying to wrap my head around this:

• I cannot install this app alongside an existing matrix/element on the same domain

Correct, same with any other matrix/synapse… software thought. You can however install it on a subdomain. But it’s probably easier to just use a different domain.

• The bare domain must be empty (no app installed)

For federation to work and because of current well-known limitations with Cloudron, i recommend setting the tld as an alias on the EMS app after installation. If/when Cloudron enables customization of the well-known endpoints, this shouldn’t be an issue anymore. Currently it’s a workaround.

• The primary location must be "account" (exact wording) and not something else e.g. comms.domain.com

It can be anything. Could be ems.matrix.domain.com, there are no naming restrictions. I simply would have preferred to host the chat (element) app on this domain but for oidc reasons this needs to be Ems. Maybe I phrased this badly in the OP.

• Running this app alongside existing matrix app on different domains BUT on the same CR is OKAY

Correct you can install this on the same Cloudron as your existing installation and won’t interfere if you don’t override domains used for that instance.

[humpty]

@andreasdueren said:

Maybe I phrased this badly in the OP.

It's definitely me. I just switched from iOS to GrapheneOS and my tech-brain is fried. So many things that "just worked" in iOS requires a bridge, an extra app, or some hack to get to work. More details here

[andreasdueren]

@humpty yes I understand, I’ve made these experiences too. My goal for this Ems package is to just fix it all and make it just all work. Lol

[andreasdueren]

Update — use v0.3.13 or later

Do not use the migration implementation from v0.3.11 or v0.3.12.
A subsequent real-data end-to-end rehearsal found and fixed several issues,
including restoring PostgreSQL while Synapse/MAS could still be running,
incorrect syn2mas configuration, loss of MAS migration bookkeeping, and
missing appservice registrations.

The corrected workflow was published in v0.3.13 and tested using a
disposable ESS installation and a copy of a real Synapse database. The live
source homeserver was not modified.

Migration must be performed with the new ESS target in Cloudron
debug/recovery mode, with Synapse and MAS completely offline. Follow the
current docs/MIGRATION.md,
not the original v0.3.11 instructions below.

Migration from existing Synapse package now available in v0.3.11

I added a first guided migration path for moving an existing Synapse homeserver into the ESS Cloudron package.

This is experimental: Don't use in production unless you know the risks.

This is meant for people currently running the old/legacy Synapse package who want to move to the new ESS stack with Matrix Authentication Service (MAS), Element X, and Element Call, without asking every user to log in again.

The package now ships a helper script:

/app/pkg/src/migrate-from-synapse.sh  

It uses Element's official mas-cli syn2mas migration tooling under the hood.

What it preserves

The goal is a real homeserver migration, not a fresh start.

The migration is designed to preserve:

Data	Preserved?	Notes
Matrix server name		Must stay exactly the same
Users		Existing users are imported
Password hashes		Old Synapse bcrypt hashes continue working
Password pepper		Auto-detected from old homeserver.yaml if present
Existing sessions		Users should stay logged in
Devices		Existing clients/devices are imported
Access tokens		No forced logout expected
SSO/OIDC account links		Existing Synapse OIDC provider is mapped to MAS
Rooms / room history		Comes from the Synapse database
E2EE data		Comes from the Synapse database
Media store		Copied from the old media store
Signing key		Reused, so federation identity stays intact

In other words: the intention is that users do not need to take any action.

Important requirements

This is only for migrations where the Matrix server name stays identical.

For example, if your current users are:

@alice:example.com  
@bob:example.com  

then the ESS app must also be installed for server name:

example.com  

You cannot migrate example.com to matrix.example.com or to a different domain. Matrix server names are permanent.

Other requirements / caveats:

• SAML/LDAP/custom password providers are not supported by MAS directly.
• OIDC/SSO migrations should work, but the old Synapse OIDC provider must be mapped to the new MAS provider.
• The old and new apps cannot serve the same Matrix domains at the same time, so plan a short maintenance window for the final domain switch.
• This is still new — please test on a copy first.

How it works

The script expects migration files in:

/app/data/migration/  

Required files:

/app/data/migration/homeserver.yaml  
/app/data/migration/synapse.dump  
/app/data/migration/signing.key  

Optional but recommended:

/app/data/migration/media/  

Where:

File	Description
homeserver.yaml	The old Synapse config
synapse.dump	PostgreSQL dump of the old Synapse database, preferably pg_dump -Fc
signing.key	The old Synapse signing key
media/	The old Synapse media store

The script then:

1. Checks that the old and new server_name match.
2. Detects the old Synapse OIDC provider ID.
3. Detects Synapse password pepper if configured.
4. Takes a rollback snapshot of the new ESS app's current database/secrets.
5. Restores the old Synapse database into the new ESS app.
6. Copies the old signing key and media store.
7. Configures MAS to accept imported Synapse password hashes.
8. Configures MAS to map the old Synapse OIDC provider to the Cloudron OIDC provider.
9. Runs Element's official mas-cli syn2mas.
10. Leaves existing sessions/devices/access tokens imported into MAS.

Usage

Open a Web Terminal in the new ESS app and run:

/app/pkg/src/migrate-from-synapse.sh check  

This performs preflight checks only.

Then run:

/app/pkg/src/migrate-from-synapse.sh dry-run  

This performs a full rehearsal using syn2mas --dry-run.

The dry run is the important safety step. It should detect most problems before the real migration, including:

• server name mismatch
• unsupported password configuration
• unmapped SSO provider
• invalid database/config assumptions

If the dry run is clean, run the real migration:

/app/pkg/src/migrate-from-synapse.sh migrate  

The real migration requires typing:

MIGRATE  

as confirmation.

Afterwards, restart the app and switch the domains from the old Synapse/Element apps to the new ESS app.

Rollback / reverse migration

There are two safety mechanisms.

1. The old Synapse app is not touched

The migration reads from a database dump and copied files. It does not modify the old live Synapse app.

So before the final domain switch, the safest rollback is simply:

stop the ESS app → keep using the old Synapse app  

2. Script rollback for the ESS app

The script also creates a snapshot of the ESS app before replacing its database.

To restore that snapshot:

/app/pkg/src/migrate-from-synapse.sh rollback  

This requires typing:

ROLLBACK  

as confirmation.

This is useful if you want to retry a failed migration attempt from a clean ESS state.

However, Element's syn2mas migration itself is one-way. A true "MAS back to legacy Synapse auth after live use" migration does not exist upstream. Once users have actively used the migrated server, rolling back means losing anything that happened after the migration.

Example export from old Cloudron Synapse

In the old Synapse app's Web Terminal:

pg_dump -h "${CLOUDRON_POSTGRESQL_HOST}" -p "${CLOUDRON_POSTGRESQL_PORT}" \  
  -U "${CLOUDRON_POSTGRESQL_USERNAME}" -d "${CLOUDRON_POSTGRESQL_DATABASE}" \  
  -Fc -f /tmp/synapse.dump  

Then copy these into the new ESS app:

/tmp/synapse.dump  
/app/data/configs/homeserver.yaml  
the file referenced by signing_key_path  
the directory referenced by media_store_path  

into:

/app/data/migration/  

Status

I have tested the script flow end-to-end with stubbed database/MAS commands:

• check
• dry-run
• confirmation handling
• migrate
• double-migration guard
• rollback

What still needs real-world testing is the actual syn2mas import against different existing Synapse deployments. If you're running the old Synapse package and are willing to test on a copy, feedback would be extremely helpful.

[andreasdueren]

Migration update: v0.3.13 tested with real Synapse data

A real end-to-end migration rehearsal has now been completed using a
disposable ESS target and a copy of an existing PostgreSQL-backed Synapse
homeserver. The live source server was not modified.

The rehearsal covered:

• restoring a real Synapse PostgreSQL database;
• preserving the original Matrix server name and signing key;
• copying the media store;
• running the official mas-cli syn2mas dry run and real import;
• importing human users, password hashes, OIDC links, devices, sessions, and
  access tokens;
• verifying an imported access token against
  /_matrix/client/v3/account/whoami;
• preserving existing appservice registrations;
• retaining rooms, history, E2EE/device data, and media;
• restoring the clean ESS target through the rollback command.

The test uncovered several problems in the original v0.3.11 workflow. These
included ineffective process shutdown, the wrong Synapse configuration being
passed to syn2mas, MAS migration metadata being removed during database
restore, warning exit codes being treated as failures, and appservice
registrations not being copied.

These issues are fixed in v0.3.13.

Do not use v0.3.11 or v0.3.12 for migration. Use v0.3.13 or later.

The corrected process requires putting only the new ESS target into Cloudron
debug/recovery mode so Synapse and MAS are completely offline before the
database is restored. The source Synapse installation remains untouched and
continues to be the fallback until the final domain cutover.

Current instructions:

https://git.due.ren/andreas/cloudron-ess/-/blob/main/docs/MIGRATION.md

Although the workflow has now passed a real-data rehearsal, migration should
still be treated as a maintenance operation: take backups, rehearse with a
copy, inspect the syn2mas warnings, and plan the domain cutover carefully.

[humpty]

I set up a new server. The installation went smoothly. I logged in via Cloudron using two different CR users.

User 1: logged in to element x on iOS
User 2: logged in to element x on GrapheneOS/Android (installed thru google play store)

iOS to Android:

• Text messages
• Audio calls
• Video calls

I'll test iOS to iOS when I get my hands on fam devices tonight.

Edit: BTW, I tried the option "blur background" in the video settings and things became REALLY laggy on my Pixel 10. I enabled it during the call. Maybe that's why.

[andreasdueren]

Migration update: guided one-command Synapse → ESS wizard in v0.3.17

The migration workflow has now been wrapped in an interactive wizard. After installing a fresh ESS target on temporary domains, run this on a Mac or Linux computer where the Cloudron CLI is installed and logged in:

bash <(curl -fsSL https://git.due.ren/andreas/cloudron-ess/-/raw/v0.3.17/scripts/cloudron-synapse-to-ess.sh)

No migration arguments are required. The wizard asks for:

1. the domain of the old Cloudron Synapse app;
2. the primary domain of the fresh ESS target;
3. rehearsal or final migration;
4. explicit confirmation before starting;
5. a second confirmation after the complete syn2mas dry-run.

In final mode it freezes the old homeserver before the database dump, leaves both apps safely offline for the domain switch, and starts ESS only after the operator confirms CUTOVER-DONE.

The wizard handles Cloudron backups, PostgreSQL export/restore, the original signing key and server name, appservice registrations, local media, S3 configuration, target recovery mode, preflight checks, the official syn2mas dry-run/import, and rollback.

One important media detail: local media is copied even when S3 is enabled. S3 may have been enabled after older media was created, or an asynchronous upload may be incomplete. The migrated target therefore preserves the union of all local files and existing S3 objects instead of assuming the bucket is complete.

I completed a real end-to-end rehearsal through the new no-argument terminal UI using a fresh disposable ESS target and an existing Cloudron Synapse database. It completed with exit code 0 and verified:

• 3,061 Synapse user rows and all 45 human users;
• matching imported human compatibility sessions;
• 29,533 local media files / 2,389,933,963 bytes;
• identical signing-key and S3-provider fingerprints;
• identical contents for both appservice registrations;
• successful read access to the existing S3 bucket;
• removal of credential-bearing staging data after success.

The old homeserver stayed online throughout the rehearsal. The disposable target was kept in recovery mode, verified, then uninstalled. Only backups created by the test were marked for immediate expiry, and they have already been cleaned up.

Documentation:

• Guided wizard: https://git.due.ren/andreas/cloudron-ess/-/blob/v0.3.17/scripts/cloudron-synapse-to-ess.md
• Full migration reference/manual fallback: https://git.due.ren/andreas/cloudron-ess/-/blob/v0.3.17/docs/MIGRATION.md

The final production domain reassignment remains an explicit Cloudron dashboard step because legacy Synapse/Element domains and bare-domain well-known setups differ between installations. The wizard does not guess or silently take over domains.