Requirements and Recommendations

What do you need to get started, covering hardware, software and your environment?

Software

Element Enterprise Server

Element Server Suite Download Page

To download the installer you require a Element Server Suite subscription tied with your EMS Account. If you are already logged in, click the link above to access the download page, otherwise login and then click the Your Account button found in the top-right of the page. Select Downloads under the On-Premise section.

It is highly recommended that you stay on the latest LTS version; by default, only LTS releases will be displayed. However you can untick the Show LTS Only toggle to see our monthly releases.

For each release you will see download options for the installer, the airgapped package (if your subscription allows) and Element Desktop MSIs:

• Installer.
  element-installer-enterprise-edition-YY.MM.00-gui.bin
  Where YY is a year indicator, MM is the month indicator and 00 is the version.
• Airgapped Package.
  element-installer-enterprise-edition-airgapped-YY.MM.00-gui.tar.gz
  Where YY is a year indicator, MM is the month indicator and 00 is the version.
• Element Desktop MSI.
  Element 1.11.66 ia32.msi & Element 1.11.66.msi

Once downloaded, copy the installer binary (and the airgapped package if needed) to the machine in which you will be running the installer from. Remember to ensure you've followed the Requirements and Recommendations page for your environment and specifically the Operating System specific Prerequisites for your intended deployment method (Standalone or Kubernetes).

Operating System

The installer binary requires a Linux OS to run, supported platforms include:

Please note that Ubuntu 24.04 LTS is only supported on ESS LTS 24.10 and later. For earlier versions, while configuration can be generated, deployment will fail.

Element Server Suite 24.04 currently only supports up to Python 3.11

• Ubuntu.

  • Ubuntu Server 20.04
  • Ubuntu Server 22.04
    
  Ubuntu Prerequisites

  Standalone Deployments

  
  

  During installation you should select docker as a package option and set up ssh.

  
  

  sudo apt-get update
  sudo apt-get upgrade
  sudo apt-get install git
  

  
  

  The installer requires that it is run as a non-root user who has sudo permissions, make sure that you have a user who can use sudo. You could create a user called element-demo that can use sudo by using the following commands (run as root):

  
  

  useradd element-demo
  gpasswd -a element-demo sudo
  

  
  

  The installer also requires that your non-root user has a home directory in /home.

  
  

  Kubernetes Deployments

  
  

  The installer needs python3, pip3 and python3-venv installed to run and uses your currently active kubectl context. This can be determined with kubectl config current-context, make sure this is the correct context as all subsequent operations will be performed under it.

  
  

  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.

  
  

Other Debian based distros

While we only officially support the above Ubuntu versions, other Debian based distos are known to work. FOr example Debian. Make sure you

• Enterprise Linux. RHEL, CentOS Stream, etc.

  • Enterprise Linux 8
  • Enterprise Linux 9
    
  Enterprise Linux Prerequisites

  Standalone Deployments

  
  

  During installation make sure to select "Container Management" in the "Additional Software" section.

  
  

  sudo yum update -y
  sudo yum install python39-pip python39-devel make gcc git -y
  sudo yum install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm -y
  sudo update-alternatives --config python3
  

  On minimal installations, you may also need to install tar and python3-libsemanage

  
  

  You should also follow the steps linked here to Install microk8s on RHEL, or included below, if you run into Error: System does not fully support snapd: cannot mount squashfs image using "squashfs":

  
  

  1. Install the EPEL repository

     • RHEL9:

       sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-9.noarch.rpm
       sudo dnf upgrade
       

     • RHEL8:

       sudo dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm
       sudo dnf upgrade
       

  2. Install Snap, enable main snap communication socket and enable classic snap support

     sudo yum install snapd
     sudo systemctl enable --now snapd.socket
     sudo ln -s /var/lib/snapd/snap /snap
     

  3. Reboot

  On the update-alternatives command, if you see more than one option, select the option with a command string of /usr/bin/python3.9.

  
  

  The installer requires that it is run as a non-root user who has sudo permissions, make sure that you have a user who can use sudo. You could create a user called element-demo that can use sudo by using the following commands (run as root):

  
  

  useradd element-demo
  gpasswd -a element-demo wheel
  

  
  

  The installer also requires that your non-root user has a home directory in /home.

  
  

  Kubernetes Deployments

  
  

  The installer needs python3, pip3 and python3-venv installed to run and uses your currently active kubectl context. This can be determined with kubectl config current-context, make sure this is the correct context as all subsequent operations will be performed under it.

  
  

  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.

For installation in Standalone mode, i.e. onto the host itself, only the above OS's are supported, otherwise for an installation into a Kubernetes environment, make sure you have a Kubernetes platform deployed that you have access to from the host running the installer.

Hardware

Regardless of if you pick the standalone server or Kubernetes deployment, you will need a base level of hardware to support the application. The general guidance for server requirements is dependant on your Federation settings:

• Open Federation.
  Element recommends a minimum of 8 vCPUs/CPUs and 32GB ram for the host(s) running synapse pods.

• Closed Federation.
  Element recommends a minimum of 6 vCPUs/CPUs and 16GB ram for the host(s) running synapse pods.

The installer binary requires support for the x86_64 architecture. Note that for Standalone deployments, hosts will need 2 GiB of memory to run both the OS and microk8s and should have at least 50Gb free space in /var.

Component-Level Requirements

Please note that these values below are indicative and might vary a lot depending on your setup, the volume of federation traffic, active usage, bridged use-cases, integrations enabled, etc. For each profile below:

• CPU is the maximum cpu cores the Homeserver can request
• Memory is the average memory the Homeserver will require

Synapse Homeserver

The installer comes with default installation profiles which configure workers depending on your setup.

Synapse Postgres Server

Synapse postgres server will require the following resources :

Operator & Updater

The Updater memory usage remains at 256Mi. At least 1 CPU should be provisioned for the operator and the updater.

The Operator memory usage scales linearly with the number of integrations you deploy with ESS. It's memory usage will remain low, but might spike up to 256Mi x Nb Integrations during deployment and configuration changes.

Synapse Media

The disk usage to expect after a year can be calculated using the following formula:

• average media size × ( average number of media uploaded ÷ day ) × active users × 365.

Media retention can be configured with the configuration option in Synapse/Config/Data Retention of the installer.

Postgres DB size

The disk usage to expect after a year can be calculated using the following formula:

• If Federation is enabled, active users × 0.9GB.
• If Federation is disabled or limited, active users × 0.6GB.

Environment

For each of the components you choose to deploy (excluding postgresql, groupsync 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.

In addition to hostnames for each component, 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:

• Base Domain.
  example.com
• Synapse.
  matrix.example.com
• Element Web.
  element.example.com
• Integration Manager.
  integrator.example.com
• Admin Dashboard.
  admin.example.com
• AdminBot.
  adminbot.example.com
• AuditBot.
  auditbot.example.com
• Hookshot.
  hookshot.example.com
• Hydrogen.
  hydrogen.example.com
• Jitsi.
  jitsi.example.com
• Coturn.
  coturn.example.com
• Element Call.
  call.example.com
• SFU.
  sfu.example.com
• Grafana.
  grafana.example.com
• Telegram Bridge.
  telegrambridge.example.com
• Teams Bridge.
  teamsbridge.example.com

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.

Standalone Environment Prerequisites

Before beginning the installation of a Kubernetes deployment, there are a few things that must be prepared to ensure a successful deployment and functioning installation.

Server Minimum Requirements

It is crucial that your storage provider supports fsync for data integrity.

• /var: 50GB
• /data/element-deployment: The default directory that Will contain your Synapse media. See the Synapse Media section above to find an estimation of the expected size growth.
• /data/postgres: The default directory that Will contain your Postgres database. See the Postgres DB size section above to find an estimation of the expected size.

Check out the ESS Sizing Calculator for further guidance which you can tailor to your specific desired configuration.

Kernel Modules

While above the supported Operating Systems should have this already, please note that microk8s requires the kernel module nf_conntrack to be enabled.

if ! grep nf_conntrack /proc/modules; then
    echo "nf_conntrack" | sudo tee --append /etc/modules
    sudo modprobe nf_conntrack
fi

Network Proxy

If your environment requires proxy access to get to the internet, you will need to make the folllowing changes to your operating system configuration to enable our installer to access the resources it needs over the internet.

HTTPS_PROXY=http://corporate.proxy:3128
HTTP_PROXY=http://corporate.proxy:3128
https_proxy=http://corporate.proxy:3128
http_proxy=http://corporate.proxy:3128
NO_PROXY=10.1.0.0/16,10.152.183.0/24,127.0.0.1,*.svc
no_proxy=10.1.0.0/16,10.152.183.0/24,127.0.0.1,*.svc

export HTTP_PROXY=http://corporate.proxy:3128
export HTTPS_PROXY=http://corporate.proxy:3128
export http_proxy=http://corporate.proxy:3128
export https_proxy=http://corporate.proxy:3128
export NO_PROXY=10.1.0.0/16,10.152.183.0/24,127.0.0.1,localhost,*.svc
export no_proxy=10.1.0.0/16,10.152.183.0/24,127.0.0.1,localhost,*.svc

Once your OS specific steps are complete, you will need to log out and back in for the environment variables to be re-read after setting them. If you already have microk8s running, you will need to run the following to have microk8s reload the new environment variables:

microk8s.stop
microk8s.start

If you need to use an authenticated proxy, then the URL schema for both EL and Ubuntu is as follows:

protocol:user:password@host:port

So if your proxy is corporate.proxy and listens on port 3128 without SSL and requires a username of bob and a password of inmye1em3nt then your url would be formatted:

http://bob:inmye1em3nt@corporate.proxy:3128

For further help with proxies, we suggest that you contact your proxy administrator or operating system vendor.

PostgreSQL

The installation requires that you have a postgresql database; if you do not already have a database, then the standalone installer will set up PostgreSQL on your behalf.

If you already have PostgreSQL, the installation requires that the database is setup with a locale of C and use UTF8 encoding

See Synapse Postgres Setup Docs for further details.

Once setup, or if you have this already, make note of the database name, user, and password as you will need these when configuring ESS via the installater GUI.

Kubernetes Environment Prerequisites

Before beginning the installation of a Kubernetes deployment, there are a few things that must be prepared to ensure a successful deployment and functioning installation.

PostgreSQL

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 UTF8 encoding

Look at the Synapse Postgres Setup Docs 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 CrashLoopBackoff cycle.

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:

helm repo add bitnami https://charts.bitnami.com/bitnami
helm repo update
helm search repo bitnami/postgresql                                                                                                                                                                                                        ~/Desktop
NAME                    CHART VERSION   APP VERSION     DESCRIPTION                                       
bitnami/postgresql      12.5.7          15.3.0          PostgreSQL (Postgres) is an open source object-...
bitnami/postgresql-ha   11.7.5          15.3.0          This PostgreSQL cluster solution includes the P...

auth:
  # This is the necessary configuration you will need for the Installer, minus the hostname
  database: "synapse"

  username: "synapse"
  password: "PleaseChangeMe!"

primary:
  initdb:
    # This ensures that the initial database will be created with the proper collation settings
    args: "--lc-collate=C --lc-ctype=C"

  persistence:
    enabled: true
    # Set this value if you need to use a non-default StorageClass for your database's PVC
    # storageClass: ""
    size: 20Gi


  # Optional - resource requests / requirements
  # These are sufficient for a 10 - 20 user server
  resources:
    requests:
      cpu: 500m
      memory: 512Mi
    limits:
      memory: 2Gi

# format:
# helm install --create-namespace -n <namespace> <helm-release-name> <repo/chart> -f <values file> (-f <additional values file>)

helm install --create-namespace -n postgresql postgresql bitnami/postgresql -f values.yaml 

-- snip --

PostgreSQL can be accessed via port 5432 on the following DNS names from within your cluster:

    postgresql.postgresql.svc.cluster.local - Read/Write connection
-- snip --

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.

controller:
  ingressClassResource:
    name: nginx
    default: true
    enabled: true

# format:
# kubectl get service -n <namespace> <release-name>-ingress-nginx-controller
$ kubectl get service -n ingress-nginx k3s-ingress-nginx-controller

NAME                                   TYPE           CLUSTER-IP      EXTERNAL-IP                                               PORT(S)                      AGE
k3s-ingress-nginx-controller            LoadBalancer   10.43.254.210   192.168.1.129                                             80:30634/TCP,443:31500/TCP   79d

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
Name:         nginx
Labels:       app.kubernetes.io/component=controller
              app.kubernetes.io/instance=ingress-nginx
              app.kubernetes.io/managed-by=Helm
              app.kubernetes.io/name=ingress-nginx
              app.kubernetes.io/part-of=ingress-nginx
              app.kubernetes.io/version=1.1.1
              argocd.argoproj.io/instance=ingress-nginx
              helm.sh/chart=ingress-nginx-4.0.17
Annotations:  ingressclass.kubernetes.io/is-default-class: true
Controller:   k8s.io/ingress-nginx
Events:       <none>

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.

Airgapped Environments

An airgapped environment is any environment in which the running hosts will not have access to the greater Internet. As such these hosts will be unable to get access to the required software from Element and will also be unable to share telemetry data back with Element.

Your airgapped machine will still require access to airgapped linux repositories depending on your OS. If using Red Hat Enterprise Linux, you will also need access to the EPEL Repository in your airgapped environment.

If you are going to be installing into an airgapped environment, you will need a subscription including airgapped access and to then download the airgapped dependencies element-enterprise-installer-airgapped-<version>-gui.tar.gz file, which is a ~6GB archive that will need to be transferred to your airgapped environment.

Extract the archive, using tar -xzvf element-enterprise-installer-airgapped-<version>-gui.tar.gz so that you have an airgapped directory. Once complete, your host will be successfully setup for airgapped and ready for when you need to point the installer to that directory during installation.

For Kubernetes deployments, please note that once the image upload has been done, you will need to copy the airgapped/images/images_digests.yml file to the same path on the machine which will be used to render or deploy element services. Doing this, the new image digests will be used correctly in the kubernetes manifests used for deployment.