Installing Element Server Suite

First-time installation, Upgrading or Reconfiguring ESS? See here for advice on getting started.

First-Time Installation

Make sure you've read the Requirements and Recommendations page so your environment is ready for installation.

Getting the Installer

Element Server Suite Download Page

To download the installer you require a subscription tied with your EMS Account. If you are already logged in, click the link above to access the download page, otherwise login then click the You 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 release will be displayed however you can untick the Show LTS Only toggle to see our monthly releases.

Per 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).

First-Time Installation

Make sure you've read the Requirements and Recommendations page so your environment is ready for installation.

Running the Installer

Once the binary is on the device you wish to run the installer from, make it executable using chmod +x then run it to begin:

chmod +x ./element-installer-enterprise-edition-YY.MM.00-gui.bin

export K8S_AUTH_CONTEXT=kube_context_name

./element-installer-enterprise-edition-YY.MM.00-gui.bin

With the installer running you will need to open a web browser and browse to one of the presented 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 which 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, this is due to the installer initially using a self-signed certificate. Once you have completed deployment, the installer will use a certificate you specify or the certficate supplied for the admin domain on the Domains Section.

To proceed, click 'Advanced' then 'Continue', exact wording may vary across browsers.

The Installer

With the installer running, you will initially be presented with a 'Welcome to Element!' screen, from here you can click the 'Let's Go!' button to start configuring your ESS deployment. The installer has a number of sections to work through to configure your config before starting deployment, below will detail each section and what you can configure.

You can click on any sections' header, or the provided link below it, to visit that sections' detailed breakdown page which runs through what each specific option in that section does - however do please note that not all setups will require changing from the default settings.

Host Section.

The first section of the ESS installer GUI is the Host section, here you will configure essential details of how ESS will be installed including; deployment type; subscription credentials; PostgreSQL to use; and whether or not your setup is airgapped.

For detailed guidance / details on each config option, check the Detailed Section Overview. Specifically for airgapped deployments, see the Airgapped notes.

Standalone Deployment

Ensure Standalone is selected, then if you are using LetsEncrypt for your certificates, you will want to make sure that you select Setup Cert Manager and enter an email address for LetsEncrypt to associate with your certificates. If you are using custom certificates or electing to manage SSL certificates yourself, then you will want to select Skip Cert Manager.

Provide your EMS Image Store Username and Token associated with your subscription, which you can find at https://ems.element.io/on-premise/subscriptions.

By default, microk8s will set up persistent volumes in /data/element-deployment and will allow 20GB of space to do this; ESS will configure the default DNS resolvers to Google (8.8.8.8 and 8.8.4.4); and a PostgreSQL database will be created for you. These defaults are suitable for most setups however change as needed i.e. if you need to use your company's DNS servers. If you elect to setup your own PostgreSQL database, make sure it is configured per the Requirements and Recommendations.

Kubernetes Deployment

Ensure Kubernetes Application is selected, then specify the Kubernetes context name for which you are deploying into. You can 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 those options as default.

Provide your EMS Image Store Username and Token associated with your subscription, which you can find at https://ems.element.io/on-premise/subscriptions.

Domains Section.

The second section of the ESS installer GUI is the Domains section, here you will configure the fully-qualified domain names for each of the main components that will be deployed by ESS.

On this page, we get to specify the domains for our installation. In this example, we have a domain name of example.com and this would mean our MXIDs would look like @username:example.com.

The domain page performs a check to ensure that the host names provided resolve. Once you get green checks across the board, you can click continue.

For detailed guidance / details on each config option, check the Detailed Section Overview

Certificates Section.

The third section of the ESS installer GUI is the Domains section, here you will configure the certificates to use for each previously specified domain name.

If you are already hostserving acontent on your base domaindomain, example.complease onread athe web server, then Well-Known Delegation notes specifically to understand how you should beconfigure setthis tocomponents' Externally Managed.

This is because Element clients need to be able to request https://example.com/.well-known/matrix/client to work properly. The web server hosting the domain name should forward requests to .well-known/matrix/client to the element enterprise server so that the wellKnownPod can serve it to the clients, otherwise a copy of the well known file will need to be added directly on the example.com web server.

If you don't already host a base domain example.com, then the wellKnownPod hosts the well-known file and serves the base domain example.com.certificates.

If you wish to use your own certificates they must be in PEM encoded format, for detailed guidance / details on each config option, check the Detailed Section Overview

MediaDatabase Section.

The fourth section of the ESS installer GUI is the Database section, here you will provide the configuration of the PostgreSQL databse you will be using for Synapse.

If you're running in Standalone mode, and opted for the installer deployed postgres, you will not see this section.

Make sure you've read the Requirements and Recommendations page so your environment is ready for installation. Specifically for PostgreSQL, ensure you have followed the guidance specific to your deployment:

• Standalone Deployment PostgreSQL Requirements
• Kubernetes Deployment PostgreSQL Requirements

On this page you simply need to specify the database name, the database host name, the port to connect to, the SSL mode to use, and finally, the username and password to connect with. Once you have completed this section, simply click continue.

For Standalone Deployments, if your database is installed on the same server you are installing ESS to, esnure that the servers' public IP address is used. As the container is not sharing the host network namespace, entering 127.0.0.1 will resolve to the container itself and cause the installation failure.

For detailed guidance / details on each config option, check the Detailed Database Section Overview

ClusterMedia Section.

The fifth section of the ESS installer GUI is the Media section, here you will configure where media will be saved as well as the maximum media upload size.

You can opt to use either a Persistent Volume Claim (default) or if you wish to use an S3 bucket. Selecting S3 will then require you to provide your S3 connection details and authentication credentials. You will also be able to adjust the maximum media upload size for your homeserver.

For detailed guidance / details on each config option, check the Detailed Media Section Overview

SynapseCluster Section.

The sixth section of the ESS installer GUI is the Cluster section, here you will configure settings specific to the cluster in which Element Deployment will run on top of.

On standard setups, no options need configuring here so you can click continue.

For setups where on the certificates section, you uploaded certificates signed by you own private Certificate Authority, you will need to upload it's certificate in PEM encoded format. This should be a full chain certificate, like those upload in the Certificates section, including the Root Certificate Authority as well as any Intermediate Certificate Authorities.

If you are in an environment where you have self-signed certificates, you will want to disable TLS verification, by clicking Advanced and then scrolling down and unchecking Verify TLS. Please bear in mind that disabling TLS verification and using self-signed certificates is not recommended for production deployments.

If your host names are not DNS resolvable, you need to use host aliases and this can be set up here. You will also click "Advanced" and scroll down to the "Host Aliases" section in "k8s". In here, you will click "Add Host Aliases" and then you will specify an IP and host names that resolve to that IP:

For detailed guidance / details on each config option, check the Detailed Cluster Section Overview

Kubernetes Deployment

If you are not using OpenShift, you will need to set Force UID GID and Set Sec Comp to Enable under the section Security Context so that it looks like:

If you are using OpenShift, you should leave the values of Force UID GID and Set Sec Comp set to Auto.

Synapse Section.

The seventh section of the ESS installer GUI is the Synapse section, here you will configure settings specific to your homeserver.

While there are lots of options that can be configured in the section, it is generally recommended to complete the first-time setup before toggling on additional features i.e. Delegated Authentication, Data Retention etc.

Re-running the installer and configuring these individually after first-time setup is recommend to make troubleshooting easier should something in this section be mis-configured.

Generally speaking, for first-time setup the default options here can be left as-is, as they can be altered as needed post-deployment. Simply click continue to advance, however see below for details on some options you may wish to alter.

The first setting that you will come to is our built in performance profiles. Select the appropriate answers for Monthly Active Users and Federation Type to apply our best practices based on years of running Matrix homeservers.

Setting of Monthly Active Users^{aka MAU} and Federation Type within the Profile section does not directly set the maximum monthly active users or open/close Federation. These options will simply auto-configure the number of underlying pods deployed to handle the advised values.

You will be able to directly configure your desired maximum MAU and Federation in dedicated sections.

The next setting that you will see is whether you want to auto accept invites. The default of Manual will fit most use cases, but you are welcome to change this value.

The next setting is the maximum number of monthly active users (MAU) that you have purchased for your server. Your server will not allow you to go past this value. If you set this higher than your purchased MAU and you go over your purchased MAU, you will need to true up with Element to cover the cost of the unpaid users.

The next setting concerns registration. A server with open registration on the open internet can become a target, so we default to closed registration. You will notice that there is a setting called Custom and this requires explicit custom settings in the additional configuration section. Unless instructed by Element, you will not need the Custom option and should instead pick Closed or Open depending on your needs.

After this, you will see that the installer has generated a random admin password for you. You will want to use the eye icon to view the password and copy this down as you will use this with the user onprem-admin-donotdelete to log into the admin panel after installation.

Continuing, we see telemetry. You should leave this enabled as you are required to report MAU to Element. In the event that you are installing into an enviroment without internet access, you may disable this so that it does not continue to try talking to Element. That said, you are still required to generate an MAU report at regular intervals and share that with Element.

For more information on the data that Element collects, please see: What Telemetry Data is Collected by Element?

As mentioned above, there are a lot of options that can be configured here, it is recommended to run through the detailed guidance / details on each config option available on the Detailed Synapse Section Overview

Delegated Auth.

For detailed guidance / details on each config option, check the Detailed Delegated Auth Section Overview

Federation.

For detailed guidance / details on each config option, check the Detailed Federation Section Overview

Element Web Section.

For detailed guidance / details on each config option, check the Detailed Section Overview

Homeserver Admin Section.

For detailed guidance / details on each config option, check the Detailed Section Overview

Integrator Section.

For detailed guidance / details on each config option, check the Detailed Section Overview

Reconfiguring an existing Installation

Notes

Upgrading an existing Installation

Notes

• Prior to download a new version of the installer, it is important to check all upgrade notes that may affect you (any since the version you are currently on). If you are upgrading from one version of the same LTS to another, check
• When you first run a new version of the installer, your config may be upgraded. Once this is complete, go through all sections within the installer, re-confirm all options (making sure to save any changes / click save on any pages that do not have it greyed out), enable Dry Run in Group Sync (if configured) then hit Deploy.