# ess-helm: Element's Helm charts for a self-hosted Matrix server

> The Element Server Suite Community Edition is a set of Helm charts and tooling for running a Matrix deployment on Kubernetes, with Synapse, the new authentication service, Element Web, Element Call and Element Admin in the box. It is free for non-commercial use up to a hundred users, and the paid edition is where the interesting features live.

**element-hq/ess-helm** — Element Server Suite Community Edition

- Repository: https://github.com/element-hq/ess-helm
- Website: https://element.io/server-suite
- Stars: 999 · Forks: 155
- Language: Python
- License: AGPL-3.0
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/element-hq-ess-helm

## What the community edition is, and who it is aimed at

Element Server Suite Community Edition, usually shortened to ESS Community, is a distribution rather than a single program. It lets you deploy a Matrix stack using the provided Helm charts and a Kubernetes distribution of your choice, and the project is explicit that it is meant to be usable even if you have no Kubernetes knowledge.

The positioning is stated plainly. It is the official Matrix stack from Element for non-commercial use, provided for community use cases with quality in mind, and it aims to be as easy to use as possible while still fully supporting Matrix 2.0. The target scale is small to mid-size and up to 100 users.

Two features of that sentence deserve attention. The charts are described as including the latest features of the Matrix server Synapse and other components, so this is a tracking release of the current upstream rather than a conservative fork. And the licence is AGPLv3, which means the code is open and the copyleft obligation applies to anyone who modifies it and offers the modified version over a network.

The deployment target is Kubernetes, but the project does not require a managed cloud Kubernetes service. The setup guide in the repository starts from K3S, the single node Kubernetes distribution, which means a community can run the whole stack on one modest machine and move to a larger cluster later.

## Three editions, and the features that live behind the paywall

There are three editions of the suite, and the community one is the smallest. Knowing what is missing is more useful than knowing what is present when you are deciding.

ESS Pro is the commercial distribution. It adds multi-tenancy for running many small hosts, more efficient and cloud-native Synapse subsystems for individual large hosts, dynamic and automatic scaling in both directions based on real load, in-cluster high availability, and an improved end-user experience through better stability under load. It uses Synapse Pro, which the vendor claims brings resource and operational cost savings of up to 90 percent compared to the community edition depending on usage patterns.

The security and identity features are the bigger practical difference. Pro includes an application-level firewall with federation controls in the form of Element's Secure Border Gateway, user lifecycle management and group access control through LDAP and SCIM, malware scanning of media attachments, auditing through AuditBot, supervision and central control through AdminBot, LDAP support for user authentication, S3 for media storage, and distroless or minimal images of the core components. It also adds L3 support, long-term support, an advanced security advisory process, and preparation for the Cyber Resilience Act.

The third edition, ESS TI-M, is a special version of Pro aimed at the requirements of TI-Messenger Pro and ePA as specified by the German National Digital Health Agency Gematik. It complies with a specific Matrix version and does not use experimental features.

For a community that hits the 100 user ceiling, the upgrade path is a contact with the vendor rather than a self-service button, and the documentation puts the comparison table and the Pro documentation at separate URLs.

## The components that ship in the box

The community edition is not Synapse with a web client bolted on. Five components are listed as included out of the box, and they map onto the moving parts of a Matrix deployment.

Synapse is the Matrix server itself, and the project uses the upstream Element-hosted Synapse repository rather than a bundled fork. The Matrix Authentication Service is the component that manages users and handles user authentication, and its presence is the most significant architectural fact in the list, because it is the newer approach to Matrix identity and it changes how you create and manage accounts.

Element Call's Matrix RTC Backend allows Element Call to be used from the Element X and Element Web apps, which is what makes group voice and video work through the client rather than through a separate application.

Element Web is the Matrix web client provided by Element, and Element Admin is the administration interface. Both are the Element-branded applications, so a deployment is a complete user-facing stack rather than a server that leaves you to pick clients.

The repository structure backs this up. The charts directory holds the Helm charts, the packages directory holds workspace members, and there is a separate matrix-tools directory, a tests directory, a docs directory, a scripts directory and a newsfragments directory. The presence of newsfragments alongside a changelog is the towncrier convention, where each change arrives as a small file and the changelog is assembled at release time, which is a good sign for a project with many contributors.

## A Python project that happens to ship charts

The surprise in the repository is that ess-helm is as much a Python project as a chart repository, and the tooling is modern.

The package metadata is minimal, and the project is named for the community distribution:

```toml
name = "ess-community"
version = "0.1.0"
license = "AGPL-3.0-Only, Element Commercial"
requires-python = ">=3.11,<4.0"
```

The Python version floor of 3.11 tells you the project targets current interpreters, and the license field deserves a second look. It reads AGPL-3.0-Only together with an Element Commercial tag, which is the machine readable form of the split between the community terms and the commercial ones described in the editions section. The repository also ships a LICENSES directory, a REUSE.toml file and a reuse tool in the development dependencies, so the licensing metadata is handled as a first class concern with a machine check rather than a paragraph in the readme.

The development dependencies list is a good map of the engineering practice: pytest with a pinned upper bound below version 9, ruff for linting with a line length of 120, mypy, checkov for infrastructure scanning, yamllint and yamale for the chart files, a jsonschema validator, towncrier for the changelog fragments, cspell for spelling, and a browser group holding Playwright that is explicitly optional because it publishes no packages for musl hosts such as Alpine.

```toml
[tool.ruff]
line-length = 120
```

The test configuration disables the pytest asyncio plugin and enforces strict markers, with a cap on concurrent asyncio tasks, and the workspace has two members, a migration tool package and the tests package. There is also a docker-bake definition, an artifacthub repository descriptor and a chart-testing configuration, which is how the charts themselves get linted and rendered before release.

## The quick setup path and its ordering

The setup guide in the repository is organised as a sequence, and the order is deliberate because several steps depend on earlier ones.

The environment comes first, and it starts with DNS. The certificate section follows, and it offers several routes: Let's Encrypt, a certificate file you supply, a wildcard certificate, individual certificates per name, and using an existing reverse proxy. The presence of the reverse proxy option matters operationally, because a Matrix deployment is federation heavy and most operators already have a proxy in front of their other services.

The database is configured next, and then the installation section covers setting up the stack, creating an initial user, and verifying the setup. The verification step is listed as its own item rather than being folded into the install, which is the right call for a system that has to federate successfully with the rest of the Matrix network to be useful.

The Kubernetes part of the guide uses K3S for a single node setup, which is the lowest friction path to a working stack and the one a community with one server should take. Beyond the quick setup there are sections for advanced setup, troubleshooting, maintenance and uninstalling, and the maintenance section is the one to read before you are in production, because a Matrix server that federates with other servers accumulates state that has to be managed over time.

A note on the example configurations: the guide includes them for a reason, since a Matrix deployment has a number of interacting services and getting the ingress, the federation port and the well-known discovery right is where most first attempts fail.

## Release cadence and the versioning scheme

The release history shows a project shipping on a calendar scheme with frequent releases. Version 26.10.0 was published on 2026-10-09, 26.10.1 on 2026-10-15 and 26.10.2 on 2026-10-16, and the last push was on 2026-10-19. The numbers are year and month with a patch counter, so the naming tells you the vintage of a chart without looking anything up.

That cadence is worth thinking about when you decide how to consume the project. Three releases in eight days is good news for someone who wants the latest Synapse behaviour and bad news for anyone who planned to pin a version and forget about it. The semver library appears in the development dependencies, so the project has tooling for working with version constraints internally, but the release numbering itself is calendar based rather than a promise about API stability.

The practical advice is to pin a specific chart version in production, read the changelog and the newsfragments before upgrading, and treat the upgrade as an operation with a rollback, not as a pull. A Matrix deployment holds user data, media and federation state, and the chart set is what decides how the components are wired together, so a chart upgrade can change the shape of the deployment as well as the version of the images it pulls.

The chart and the images are released together, which is the right way to do it, and it is also why the version number of the chart tells you which Synapse and Element Web you are getting. The upstream Matrix server keeps its own release cadence, and the suite follows it.

## Conclusion

ess-helm is a good fit for a community, a non-profit or a small company that wants a properly packaged Matrix server on Kubernetes without writing the deployment themselves, especially if the 100 user ceiling and the non-commercial condition suit you. It is the wrong choice for a commercial deployment, an organisation that needs high availability, LDAP-backed identities, media scanning or audit trails, because those live in ESS Pro. Before you deploy, read the edition comparison to confirm the community terms cover your use, plan the database and certificate steps from the setup guide, and check the release notes for your version since the chart and the bundled images move together.

## FAQ

### What does ess-helm actually deploy?

It deploys a Matrix stack on Kubernetes with Synapse as the server, the Matrix Authentication Service for user management and authentication, the Element Call Matrix RTC backend for calls from the Element clients, Element Web as the web client and Element Admin as the administration interface.

### Is ESS Community free for commercial use?

The project describes it as the official Matrix stack from Element for non-commercial use, freely available under the AGPLv3 licence and tailored to small and mid-scale community use cases with up to 100 users. Professional use and larger scale are handled by the commercial ESS Pro edition.

### Do I need a managed Kubernetes service to use ess-helm?

No. The project provides Helm charts and a Kubernetes distribution of your choice, and the setup guide starts from K3S, the single node Kubernetes distribution, so a community deployment can run on a single machine. The documentation also describes an existing reverse proxy and certificate options so an established setup can be reused.

### What are the differences between ESS Community and ESS Pro?

Pro adds Synapse Pro with multi-tenancy and cloud-native subsystems, automatic scaling, in-cluster high availability, the Secure Border Gateway for federation control, LDAP and SCIM for user lifecycle management, media malware scanning, auditing through AuditBot, supervision through AdminBot, S3 media storage, distroless images, L3 support and long-term support. A third edition, ESS TI-M, targets the TI-Messenger and ePA requirements of the German Gematik authority.

## Sources

- [element-hq/ess-helm on GitHub](https://github.com/element-hq/ess-helm)
- [License: AGPL-3.0](https://github.com/element-hq/ess-helm/blob/main/LICENSE)
- [Project website](https://element.io/server-suite)
- [README](https://github.com/element-hq/ess-helm/blob/main/README.md)
- [Releases](https://github.com/element-hq/ess-helm/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/element-hq-ess-helm