Skip to main content

Single Node Installations

How to Use the Installer

Overview

Our Element Enterprise Single Node Installer can handle the installation of environments in which only one server is available. Our single node environment consists of a single server with microk8s running that we deploy our Element Enterprise Operator to, resulting in a fully functioning Synapse server with Element Web.

To get started with a single node installation, there are several things that need to be considered and this guide will work through them:

  • Operating System
  • Postgresql Database
  • TURN Server
  • SSL Certificates
  • Extra configuration items

Once these areas have been covered, you’ll be able to install a single node environment!

Operating System

To get started, we have tested on Ubuntu 20.04 and Red Hat Enterprise Linux 8.5 and suggest that you start there as well. For x86_64, you can grab an Ubuntu iso here:

https://releases.ubuntu.com/20.04.3/ubuntu-20.04.3-live-server-amd64.iso

or you can get Red Hat Enterprise Linux 8 with a Developer Subscription

https://developers.redhat.com/content-gateway/file/rhel-8.6-x86_64-dvd.iso

Note that future references in this document to EL reference Enterprise Linux.

Ubuntu Specific Directions

Make sure to select docker as a package option. Do set up ssh.

Once you log in, please run:

sudo apt-get update
sudo apt-get upgrade
sudo apt-get install python3-signedjson pwgen -y

The installer requires that you run it as a non-root user who has sudo permissions. Please make sure that you have a user who can use sudo. If you wanted to make a user called element-demo that can use sudo, the following commands (run as root) would achieve that:

useradd element-demo
gpasswd -a element-demo sudo

EL Specific directions

Make sure to select "Container Management" in the "Additional Software" section.

Once you log in, please run:

sudo yum update -y
sudo yum install podman-docker python-pip -y
sudo yum install
https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm -y
sudo update-alternatives --setconfig python3 /usr/bin/python3.9

Add the following lines to /etc/security/limits.conf:

*              soft    nofile  100000
*              hard    nofile  100000

Then, run:

sudo yum install make gcc python39-devel pwgen -y
pip3 install signedjson --user

The installer requires that you run it as a non-root user who has sudo permissions. Please make sure that you have a user who can use sudo. If you wanted to make a user called element-demo that can use sudo, the following commands (run as root) would achieve that:

useradd element-demo
gpasswd -a element-demo wheel

Setting up the Configuration Directory

You should have the installer unpacked in a directory on your server. We will refer to this as the installer directory. You will also need to create a configuration directory that we will call the config directory. Both the parameters.yml and secrets.yml file live in the config directory.

To create the configuration directory, run the following:

mkdir ~/.element-onpremise-config

Network Specifics

Element Enterprise On-Premise needs to bind and serve content over:

  • Port 80 TCP
  • Port 443 TCP

microk8s needs to bind and serve content over:

  • Port 16443 TCP
  • Port 10250 TCP
  • Port 10255 TCP
  • Port 25000 TCP
  • Port 12379 TCP
  • Port 10257 TCP
  • Port 10259 TCP
  • Port 19001 TCP

For more information, see https://microk8s.io/docs/ports.

In a default Ubuntu installation, these ports are allowed through the firewall. You will need to ensure that these ports are passed through your firewall.

For EL, you need to explicitly open the above ports and enabling masquerading:

sudo firewall-cmd --add-service={http,https} --permanent
sudo firewall-cmd --add-port=16443/tcp --add-port=10250/tcp --add-port=10255/tcp --add-port=25000/tcp --add-port=12379/tcp --add-port=10257/tcp --add-port=10259/tcp --add-port=19001/tcp --permanent
sudo firewall-cmd --add-masquerade --permanent
sudo firewall-cmd --reload

Further, you need to make sure that your host is able to access the following hosts on the internet:

  • api.snapcraft.io
  • *.snapcraftcontent.com
  • gitlab.matrix.org
  • gitlab-registry.matrix.org
  • pypi.org
  • docker.io
  • *.docker.com
  • get.helm.sh

Further, you will also need to make sure that your host can access your distributions' package repositories. As these hostnames can vary, it is beyond the scope of this documentation to enumerate them.

Network Proxies

We also cover the case where you need to use a proxy to access the internet. Please see this article for more information: Configuring a microk8s Single Node Instance to Use a Network Proxy

Unpacking the Installer

Please make sure that you unpack element-enterprise-installer onto your single node system. The directory that it unpacks into will be referenced in this document as the installer directory.

Postgresql Database

The installation requires that you have a postgresql database with a locale of C and UTF8 encoding set up. See https://github.com/matrix-org/synapse/blob/develop/docs/postgres.md#set-up-database for further details.

If you have this already, please make note of the database name, user, and password as you will need these to begin the installation.

If you do not already have a database, then the single node installer will set up PostgreSQL on your behalf.

TURN Server

For installations in which you desire to use video conferencing functionality, you will need to have a TURN server installed and available for Element to use.

If you do not have an existing TURN server, our installer can configure one for you by following the extra steps in Setting Up Jitsi and TURN With the Installer

If you have an existing TURN server, please create a file called synapse/turn.yml in your config directory and put the following in it:

turn_uris: [ "turn:turn.matrix.org?transport=udp", "turn:turn.matrix.org?transport=tcp" ]
turn_shared_secret: "n0t4ctuAllymatr1Xd0TorgSshar3d5ecret4obvIousreAsons"
turn_user_lifetime: 86400000
turn_allow_guests: True

based on your TURN server specifics. This will allow the installer to configure synapse to use your TURN server.

A few notes on TURN servers:

  • The TURN server has to be directly accessible by end-users. Normally this means a public IP, however if all the end-users are going to be on a VPN/private network then they just need to be able to access the private IP of the TURN server.
  • The only reason to have TURN on a private network is if the private network disallows user <-> user traffic and only allows user <-> TURN server traffic. If user <-> user is allowed within the private network then a TURN server isn't needed.

SSL Certificates

For SSL Certificates, you have three options:

  • Signed PEM encoded certificates from an internet recognized authority.
  • Signed PEM encoded certificates from an internal to your company authority.
  • LetsEncrypt
  • Self-signed certificates

In the case of Signed certificates or LetsEncrypt, your hostnames must be accessible on the internet.

In the case of self-signed certificates, these are acceptable for a PoC (proof of concept) environment, but will not be supported in a production environment as the security risk would be too high. Configuring mobile clients and federation will not be possible with self-signed certificates.

You will need to configure certificates for the following names:

  • fqdn.tld
  • element.fqdn.tld
  • synapse.fqdn.tld
  • dimension.fqdn.tld
  • hookshot.fqdn.tld

Using our example hosts, this would mean that we need certificates for:

  • local
  • element.local
  • synapse.local
  • dimension.local
  • hookshot.local

Certificates without LetsEncrypt

If you have certificates for all of the aforementioned host names, then you can simply place the PEM encoded .crt and .key files in the certs directory under the configuration directory. Certificates in the certs directory must take the form of fqdn.crt and fqdn.key.

Self-signed certificates with mkcert

For information on using self-signed certificates with mkcert, please see this article: Using Self-Signed Certificates with mkcert

Certificates with LetsEncrypt

Our installer also supports using LetsEncrypt to build certificates for your host names and automatically install them into your environment. If your hosts are internet accessible, this is the easiest method and only requires an admin email address to provide to LetsEncrypt.

parameters.yml

Now it is time to set parameters.yml. A sample has been provided and to get started, it is easiest to do:

cp config-sample/parameters.yml.sample ~/.element-onpremise-config/parameters.yml

Using the example hostnames of element.local and synapse.local (not resolvable on the internet), we would set the following parameters first in parameters.yml:

domain_name: local
element_fqdn: element.local
synapse_fqdn: synapse.local

Next, we need to set the variables related to Postgres. If you do not have an existing Postgres server, do not make any changes. If you have an existing Postgres server, set the following:

postgres_create_in_cluster: false
postgres_fqdn: `Postgres Server`
postgres_user: `Postgres User`
postgres_db: `Postgres Database for Element`

The next line states:

media_size: "50Gi"

You wll want to adjust that to match the size of storage you've allocated for your media. It must be at least 50Gb.

The next section pertains to certmanager. If you are using your own certificates, please leave these items both blank, as such:

certmanager_issuer:
certmanager_admin_email:

If you have chosen to use letsencrypt, please specify “letsencrypt” for the certmanager_issue and an actual email address for who should manage the certificates for certmanager_admin_email:

certmanager_issuer: 'letsencrypt'
certmanager_admin_email: 'admin@mydomain.com'

Starting with installer 2022-08.02, we have added two mandatory variables related to telemetry data. These are max_mau_users and strict_mau_users_limit. You should set max_mau_users to the value defined in your contract with Element. If you set this number above your contractual limit, then the software will allow you to exceed your contractual limit and Element will bill you appropriately for the overage.

Setting strict_mau_users_limit to true forces synapse to cap the number of monthly active users to the value defined in max_mau_users. Say for example, you've paid Element for 1,000 monthly active users and don't want to exceed that, you would set:

max_mau_users: 1000
strict_mau_users_limit: true

Let's say that you paid Element for 1,000 monthly active users, but didn't mind going over provided that you didn't exceed 2,000 monthly active users. In this scenario, you would set:

max_mau_users: 2000
strict_mau_users_limit: true

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

You will also see two paths:

media_host_data_path: "/mnt/data/synapse-media"
# postgres_data_path: "/mnt/data/synapse-postgres"

For all installations, media_host_data_path should be uncommented. For installations in which you are letting the installer install postgresql for you, please uncomment the postgres_data_path line.

The next lines concern images_dir and local_registry. These are only needed in an air-gapped environment. If you are installing into an air-gapped environment, please see: Using the Single Node Installer in an Air-Gapped Environment

The next item in the configuration is the microk8s DNS resolvers. By default, the installer will use Google's publicly available DNS servers. If you have defined your hosts on a non-publicly available DNS server, then you should use your DNS servers instead of the publicly available Google DNS servers. Let's assume that your local dns servers are 192.168.122.253 and 192.168.122.252. To use those servers, you would need to add this line:

microk8s_dns_resolvers: "192.168.122.253,192.168.122.252"

You will also notice two lines towards the end regarding synapse_registration and tls_managed_externally. In most cases, you can leave these alone, but if you wish to close synapse registration or have your TLS managed externally, you may set them at this time.

Further, if you are not using DNS for hostname mapping, you will need to configure the host_aliases parameter in this file and that is documented in How to Setup Local Host Resolution Without DNS.

secrets.yml

Now we move on to configuring secrets.yml. You will need the following items here:

  • A Macaroon key
  • Your postgres password for the user specified in parameters.yml
  • A Registration Shared Secret
  • A signing Key
  • An EMS Image Store username and token, which will have been provided to you by Element.

To build a secrets.yml with the macaroon key, the registration shared secret, the generic shared secret, and the signing key already filled in, please run:

sh build_secrets.sh
mv secrets.yml  ~/.element-onpremise-config/

If you are using your own Postgres server, you will need to uncomment and fill in the postgres_passwd. If you are letting the installer install Postgres for you, then you will need to set a random password. You can generate a random password with:

pwgen 32 1

and then insert that value in the postgres_passwd field, making sure that you uncomment the line.

Do not forget to also set the values for ems_image_store_username and ems_image_store_token, which will both be provided by Element.

If you have a paid docker hub account, you can specify your username and password to avoid being throttled in the dockerhub_username and dockerhub_token fields. This is optional.

Extra Configuration Items

It is possible to configure anything in Synapse's homeserver.yaml or Element’s config.json.

To do so, you need to create json or yaml files in the appropriate directory under the config directory. These files will be merged to the target configuration file.

Samples are available in config-sample under the installer directory.

To configure synapse:

  • Create a directory synapse at the root of the config directory : mkdir ~/.element-onpremise-config/synapse
  • Copy the configurations extensions you want to setup from config-sample/synapse to ~/.element-onpremise-config/synapse.
  • Edit the values in the file accordingly to your configuration

To configure element:

  • Create a directory element at the root of the installer directory : mkdir ~/.element-onpremise-config/element
  • Copy the configurations extensions you want to setup from config-sample/element to ~/.element-onpremise-config/element.
  • Edit the values in the file accordingly to your configuration

For specifics on configuring permalinks for Element, please see Setting up Permalinks With the Installer

For specifics on setting up Delegated Authentication, please see Setting up Delegated Authentication With the Installer

For specifics on setting up Group Sync, please see Setting up Group Sync with the Installer

For specifics on setting up the Integration Manager, please see Setting Up the Integration Manager With the Installer

For specifics on setting up GitLab, GitHub, and JIRA integrations, please see Setting up GitLab, GitHub, and JIRA Integrations With the Installer

For specifics on setting up Chatterbox, please see: Setting Up Chatterbox

For specifics on setting up Adminbot and Auditbot, please see: Setting up Adminbot and Auditbot

For specifics on setting up the Enterprise Admin Dashboard, please see: Configuring the Enterprise Admin Dashboard

For specifics on pointing your installation at an existing Jitsi instance, please see Setting Up Jitsi and TURN With the Installer

For specifics on configuring the Teams Bridge, please see Setting Up the Teams Bridge

For specifics on configuring the Telegram Bridge, please see Setting Up the Telegram Bridge

For specifics on configuring the IRC Bridge, please see Setting Up the IRC Bridge

For specifics on configuring the XMPP Bridge, please see Setting Up the XMPP Bridge

Installation

Let’s review! Have you considered:

  • Operating System
  • Postgresql Database
  • TURN Server
  • SSL Certificates
  • Extra configuration items

Once you have the above sections taken care of and your parameters.yml and secrets.yml files are in order, you are ready to begin the actual installation.

From the installer directory, run: (Note: You can replace ~/.element-onpremise-config with whatever you have specified for your config directory.)

bash install.sh  ~/.element-onpremise-config

The first run should go for a little while and then exit, instructing you to log out and back in.

Please log out and back in and re-run the installer from the installer directory again:

bash install.sh  ~/.element-onpremise-config

Once this has finished, you can run:

kubectl get pods -n element-onprem

And you should get similar output to:

NAME                                        READY   STATUS    RESTARTS   AGE
app-element-web-c5bd87777-rqr6s             1/1     Running   1          29m
server-well-known-8c6bd8447-wddtm           1/1     Running   1          29m
postgres-0                                  1/1     Running   1          40m
instance-synapse-main-0                     1/1     Running   2          29m
instance-synapse-haproxy-5b4b55fc9c-hnlmp   1/1     Running   0          20m

At this time, you should also be able to browse to: https://fqdn and create a test account with Element on your new homeserver. Using our example values, I am able to go to https://element.local/ and register an account, sign in and begin testing!

Upgrading between installer versions

Installer 2022-08.02

Added two mandatory variables related to telemetry data:
max_mau_users and strict_mau_users_limit

They need to be set (ie: max_mau_users = 1000 and strict_mau_users_limit = true).

Back to top