Element On-Premise Documentation
Having trouble, contact us via email@example.com
- Introduction to Element Server Suite
- Kubernetes Installations
- Kubernetes Installations - Quick Start
- Single Node Installations
- Single Node Installs: Storage and Backup Guidelines
- Configuring Element Desktop
- Using the Installer in an Air-Gapped Environment
- Setting up Permalinks With the Installer
- Setting Up Well Known Delegation
- Setting up Delegated Authentication With the Installer
- Integrations and Add-Ons
- Setting Up Jitsi and TURN With the Installer
- Setting up Group Sync with the Installer
- Setting up GitLab, GitHub, JIRA and Webhooks Integrations With the Installer
- Setting up Adminbot and Auditbot
- Setting Up Hydrogen
- Setting up On-Premise Metrics
- Setting Up the Telegram Bridge
- Setting Up the Teams Bridge
- Setting Up the IRC Bridge
- Setting Up the SIP Bridge
- Setting Up the XMPP Bridge
- Setting up Location Sharing
- Removing Legacy Integrations
- Setting up Sliding Sync
- Setting up Element Call
- Setting Up the Skype for Business Bridge
- Migration from self-hosted to ESS On-Premise
- Configuring Synapse workers
- Setting up Delegated Authentication with LDAP on Windows AD
- Setting up Delegated Authentication with OpenID on Microsoft Azure
- Setting up Delegated Authentication with OpenID on Microsoft AD FS
- Getting Started with the Enterprise Helm Charts
- Automating ESS Deployment
- Kubernetes : namespace-scoped deployments
- Customize containers ran by ESS
- Support Policies
- Appendix A: Preparing Element Server Suite PoC
- How to run a Webserver on Standalone Deployments
- Notifications, MDM & Push Gateway
- Archived Documentation Repository
- Documentation Covering Installer 2023-02.02 CLI Only.
- Documentation Covering Installers From 2022.10.01 to 2023.02.01
- Documentation Covering Installers From 2022.07.03 to 2022.09.05
- Documentation covering v1 and installers prior to 2022-07.03
- Documentation Covering Installers from 2023-03.01 to 2023-05.04
- ESS Sizing
Introduction to Element Server Suite
What is Element Server Suite?
Element Server Suite provides an enterprise-grade secure communications platform that can be run either on your own premise or in our Element Cloud. Element Server Suite includes the Element Matrix Server, which provides a host of security and privacy features, including:
- Built on the Matrix open communications standard.
- Provides end to end encrypted messaging, voice, and video through a consumer style messenger with the power of a collaboration tool.
- Delivers data sovereignty.
- Affords a high degree of flexibility that can be tailored to many use cases.
- Allows secure federation within a single organisation or across a supply chain or ecosystem.
and combines them with the following Element Server Extensions:
- Group Sync: Synchronize group data from your identity provider and map these into Element spaces.
- Adminbot: Give your server administrator the ability to be admin in any rooms on your homeserver.
- Auditbot: Have an auditable record of conversations conducted on your homeserver.
- Security and feature updates: Updates are easy to deploy and handled by our installer.
- Bridges: Bridge to IRC, XMPP, Telegram, Microsoft Teams, or SIP. More coming soon.
Further, we also offer Enterprise Support, giving you access to the experts in federated, secure communications giving you confidence to deploy our platform for your most critical secure communications needs.
Given the flexibility afforded by this platform, there are a number of moving parts to configure. This documentation will step you through architecting and deploying Element Enterprise On-Premise.
Deploying to Kubernetes or to a standalone server?
Element Enterprise On-Premise can be deployed both to Kubernetes (a lightweight container orchestration platform) or a standalone server. One key benefit of going with Kubernetes is that you can add more resources and nodes to a cluster as you need them where you are capped at one node with our standalone server. In the case of our standalone server installation, we deploy microk8s (a smaller lightweight distribution of Kubernetes), which we then use for deploying our application.
In general, regardless of if you pick the standalone server or Kubernetes deployment, you will need a base level of hardware to support the application.
For scenarios that utilise open federation, Element recommends a minimum of 8 vCPUs/CPUs and 32GB ram for the host(s) running synapse pods.
For scenarios that utilise closed federation, Element recommends a minimum of 6 vCPUs/CPUs and 16GB ram for the host(s) running synapse pods.
This document gives an overview of our secure communications platform architecture:
(Please click on the image to view it at 100%.)
Comprising our secure communications platform are the following components:
- synapse : The homeserver itself.
- element-web : The Element Web client.
- integrator: Our integration manager.
- synapse admin ui : Our Element Enterprise Administrator Dashboard.
- postgresql (Optional) : Our database. Only optional if you already have a separate PostgreSQL database, which is required for a multiple node setup. Use an external DB if you have more than 300 users.
- groupsync (Optional) : Our group sync software
- adminbot (Optional) : Our bot for admin tasks.
- auditbot (Optional) : Our bot that provides auditability.
- hookshot (Optional) : Our integrations with gitlab, github, jira, and custom webhooks.
- hydrogen (Optional) : A light weight alternative chat client.
- jitsi (Optional) : Our VoIP platform for group conferencing.
- coturn (Optional) : TURN server. Required if deploying VoIP.
- element-call (Optional) : Our new VoIP plaftorm for group conferencing
- sfu (Optional) : Element Call LiveKit component for scalable conferencing
- prometheus (Optional) : Provides metrics about the application and platform.
- grafana (Optional) : Graphs metrics to make them consumable.
- telegram bridge (Optional) : Bridge to connect Element to Telegram.
- teams bridge (Optional) : Bridge to connect Element to MS Teams.
- xmpp bridge (Optional) : Bridge to connect Element to XMPP.
- irc bridge (Optional) : Bridge to connect Element to IRC.
- sip bridge (Optional) : Bridge to connect Element to SIP.
For each of the components in this list (excluding postgresql, groupsync, adminbot, auditbot, and prometheus), you must provide a hostname on your network that meets this criteria:
- Fully resolvable to an IP address that is accessible from your clients.
- Signed PEM encoded certificates for the hostname in a crt/key pair. Certificates should be signed by an internet recognised authority, an internal to your company authority, or LetsEncrypt.
It is possible to deploy Element Enterprise On-Premise with self-signed certificates and without proper DNS in place, but this is not ideal as the mobile clients and federation do not work with self-signed certificates. Information on how to use self-signed certificates and hostname mappings instead of DNS can be found in How to Setup Local Host Resolution Without DNS
In addition to hostnames for the above, you will also need a hostname and PEM encoded certificate key/cert pair for your base domain. If we were deploying a domain called example.com and wanted to deploy all of the software, we would have the following hostnames in our environment that needed to meet the above criteria:
- example.com (base domain)
- matrix.example.com (the synapse homeserver)
- element.example.com (element web)
- integrator.example.com (integration manager)
- admin.example.com (admin dashboard)
- hookshot.example.com (Our integrations)
- hydrogen.example.com (Our light weight chat client)
- jitsi.example.com (Our VoIP platform)
- coturn.example.com (Our TURN server)
- grafana.example.com (Our Grafana server)
- telegrambridge.example.com (Our Telegram Bridge)
- teamsbridge.example.com (Our Teams Bridge)
- roomadmin.example.com (AdminBot)
- audit.example.com (Audit capablility)
- element-call.example.com (Our new VoIP platform)
- sfu.example.com (Scaling for Element Call)
As mentioned above, this list excludes postgresql, groupsync, adminbot, auditbot, and prometheus.
Wildcard certificates do work with our application and it would be possible to have a certificate that validated *.example.com and example.com for the above scenario. It is key to do both the base domain and the wildcard in the same certificate in order for this to work.
Further, if you want to do voice or video across network boundaries (ie: between people not on the same local network), you will need a TURN server. If you already have one, you do not have to set up coturn. If you do not already have a TURN server, you will want to set up coturn (our installer can do this for you) and if your server is behind NAT, you will need to have an external IP in order for coturn to work.
If you are going to be installing into an airgapped environment (one without internet connectivity), you will need to also download the airgapped installer, which is ~6GB of data that will need to be transferred to your airgapped environment. More information on this can be found in our airgapped installation documentation here: https://ems-docs.element.io/books/element-on-premise-documentation/page/using-the-installer-in-an-air-gapped-environment
To obtain our software, please visit our downloads page at: https://ems.element.io/on-premise/download
Kubernetes Application (Multiple Nodes)
For an installation into a kubernetes environment, make sure you have a Kubernetes platform deployed that you have access to and head over to Kubernetes Installations. You will also need a linux computer to run the installer from. That computer should be running RHEL 8 or RHEL 9 or Ubuntu.
Standalone (Single Node)
For a standalone installation, please note that we support these on the following platforms:
- Ubuntu Server 20.04
- Enterprise Linux 8 or 9 (RHEL, CentOS Stream, etc.)
Once you have a server with one of these installed, please head over to Single Node Installations
Our Installer can handle the installation of Element Enterprise into your existing production kubernetes (k8s) environment.
Server minimum requirements
The ESS deployment resource usage is described in ESS Sizing.
Before beginning the installation, there are a few things that must be prepared to ensure a successful deployment and functioning installation.
The installer needs python3, pip3 and python3-venv installed to run.
The installer uses your currently active
kubectl context which can be determined with
kubectl config current-context - make sure this is the correct context as all subsequent operations will be performed under this.
More information on configuring this can be found in the upstream kubectl docs
Be sure to
export K8S_AUTH_CONTEXT=<kube context name> for the Installer if you need to use a context aside from your currently active one.
Before you can begin with the installation you must have a PostgreSQL database instance available. The installer does not manage databases itself.
The database you use must be set to a locale of
C and use
see https://element-hq.github.io/synapse/latest/postgres.html#set-up-database for further details as they relate to Synapse. If the locale / encoding are incorrect, Synapse will fail to initialize the database and get stuck in a
Please make note of the database hostname, database name, user, and password as you will need these to begin the installation.
For testing and evaluation purposes, you can deploy PostgreSQL to k8s before you begin the installation process - see Kubernetes Installations - Quick Start - Deploying PostgreSQL to Kubernetes for more information.
Kubernetes Ingress Controller
The installer does not manage cluster Ingress capabilities since this is typically a cluster-wide concern - You must have this available prior to installation. Without a working Ingress Controller you will be unable to route traffic to your services without manual configuration.
If you do not have an Ingress Controller deployed please see Kubernetes Installations - Quick Start - Deploying ingress-nginx to Kubernetes for information on how to set up a bare-bones
ingress-nginx installation to your cluster.
Use an existing Ingress Controller
If you have an Ingress Controller deployed already and it is set to the default class for the cluster, you shouldn't have to do anything else.
If you're unsure you can see which providers are available in your cluster with the following command:
$ kubectl get IngressClass
NAME CONTROLLER PARAMETERS AGE
nginx k8s.io/ingress-nginx <none> 40d
And you can check to see whether an IngressClass is set to default using kubectl, for example:
$ kubectl describe IngressClass nginx
Annotations: ingressclass.kubernetes.io/is-default-class: true
In this example cluster there is only an
nginx IngressClass and it is already default, but depending on the cluster you are deploying to this may be something you must manually set.
Beginning the Installation
Head to https://ems.element.io/on-premise/download and download the latest installer. The installer will be called
element-enterprise-graphical-installer-YYYY-MM.VERSION-gui.bin. You will take this file and copy it to the machine where you will be installing the Element Server Suite from. This machine will need to be running on RHEL 8, RHEL 9, or Ubuntu and have access to your kubernetes cluster network. Once you have this file on the machine in a directory accessible to your sudo-enabled user, you will run:
chmod +x ./element-enterprise-graphical-installer-YYYY-MM.VERSION-gui.bin
YYYY-MM.VERSION with the appropriate tag for the installer you downloaded.
If you have multiple kubernetes clusters configured in your kubeconfig, you will have to export the
K8S_AUTH_CONTEXT variable before running the installer :
export K8S_AUTH_CONTEXT=<kube context name>
Once you have done this, you will run:
YYYY-MM.VERSION with the appropriate tag for the installer you downloaded, and this will start a web server with the installer loaded.
You will see a message similar to:
[user@element-demo ~]$ ./element-enterprise-graphical-installer-2023-02.02-gui.bin
Using self-signed certificate with SHA-256 fingerprint:
To start configuration open:
https://192.168.122.47:8443 or https://10.1.185.64:8443 or https://127.0.0.1:8443
At this point, you will need to open a web browser and browse to one of these IPs. You may need to open port 8443 in your firewall to be able to access this address from a different machine.
If you are unable to open port 8443 or you are having difficulty connecting from a different machine, you may want to try ssh port forwarding in which you would run:
ssh <host> -L 8443:127.0.0.1:8443
replacing host with the IP address or hostname of the machine that is running the installer. At this point, with ssh connected in this manner, you should be able to use the https://127.0.0.1:8443 link as this will then forward that request to the installer box via ssh.
Upon loading this address for the first time, you may be greeted with a message informing you that your connection isn't private such as this:
In this case, you'll need to click "Advanced" and then "Continue to
The Hosts Screen
The very first page that you come to is the host screen.
You will want to make sure that "Kubernetes Application" is selected. You will then need to specify the kuberentes context name for which you are deploying into. (Hint: Use
kubectl config view to see which contexts you have access to.)
You can opt to skip the update setup or the operator setup, but unless you know why you are doing that, you should leave them alone.
The very next prompt that you come to is for an EMS Image Store Username and Token. These are provided to you by element as access tokens for our enterprise container registries. If you have lost your token, you can always generate a new token at https://ems.element.io/on-premise/subscriptions.
Here, we find the ability to set the namespaces that the application will be deployed into.
The next options on the hostpage are related to connectivity. For this guide, we are assuming "Connected" and you can leave that be. If you are doing "Airgapped", you would pick airgapped at this point and then please see the section on airgapped installations.
You are presented with the option to provide docker hub credentials. These are optional, but if you do not provide them, you may be rate limited by Docker and this could cause issues pulling container images.
Finally, we come to the host admin page, which allows you to set parameters around which domain the installer and admin console should run on post deployment. This section is optional.
The Domains Screen
On this page, we get to specify the domains for our installation. In this example, we have a domain name of airgap.local and this would mean our MXIDs would look like @kabbott:airgap.local.
Our domain page has checking to ensure that the host names resolve. Once you get green checks across the board, you can click continue.
The Certificates Screen
On the Certificates screen, you will provide SSL certificate information for well-known delegation, Synapse, Element Web, Synapse Admin, and Integrator.
If you are using Let's Encrypt, then each of the sections should look like:
If you are using certificate files, then you will see a screen like: