Element On-Premise Documentation

How to Install a POC Environment

Overview

Our Element Enterprise PoC Installer can handle the installation of Element Proof of Concept (POC) environments. Our standard POC environment is a single node server with microk8s running that we deploy our Element Enterprise Operator to, resulting in a fully functioning Synapse server with Element Web that can be used to conduct a POC. On-premise production deployments use the same installer and operator, but are intended to be deployed into a full kubernetes environment.

POC installations are not intended to be run for production purposes. You should plan on having a different installation for your production environment. The settings that you use with the installer will carry over for your production install, but your rooms and spaces will not.

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

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

Hostnames/DNS

You will need hostnames for the following pieces of infrastructure:

These hostnames must resolve to the appropriate IP addresses. If you have a proper DNS server with records for these hostnames in place, then you will be good to go.

/etc/hosts may be used as an alternative to proper DNS in a POC scenario only. In this case, you will need entries similar to:

192.168.122.39 element.local element
192.168.122.39 synapse.local synapse
192.168.122.39 dimension.local dimension
192.168.122.39 hookshot.local hookshot
192.168.122.39 local

In the absence of proper DNS, for this to work in microk8s, you will also need to add the following to your parameters.yml: (This was added in installer version 2022-05.03. If you have an installer prior to this and need this functionality, please update.)

host_aliases:
  - ip: "192.168.122.39"
    hostnames:
      - "element.local"
      - "synapse.local"
      - "hookshot.local"
      - "dimension.local"
      - "local"

Machine Size

For running a proof of concept with our installer, we support only the x86_64 architecture and recommend the following minimums:

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.5-aarch64-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

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 python39-pip -y
sudo yum install
https://dl.fedoraproject.org/pub/epel/epel-release-latest-8.noarch.rpm -y
sudo alternatives --set python3 /usr/bin/python3.9

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

*              soft    nofile  100000
*              hard    nofile  100000

Further Pre-requisites

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

Please run the following commands to create the /mnt/data directory and install the python3-signedjson and pwgen packages which will be used during the configuration of the installer.

The /mnt/data directory should have at least 50 GB of space.

sudo mkdir /mnt/data
sudo mkdir /mnt/data/synapse-media

If you will be letting the installer install the Postgres database for you, also do:

sudo mkdir /mnt/data/synapse-postgres

Ubuntu:

sudo apt-get install python3-signedjson pwgen -y

EL:

sudo yum install make gcc python39-devel pwgen -y

EL: (as a normal user)

pip3 install signedjson --user

Network Specifics

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

microk8s needs to bind and serve content over:

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:

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 make sure that the following host variables are set:

Ubuntu Specific Directions

If your company's proxy is http://corporate.proxy:3128, you would edit /etc/environment and add the following lines:

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
no_proxy=10.1.0.0/16,10.152.183.0/24,127.0.0.1

The IP Ranges specified to NO_PROXY and no_proxy are specific to the microk8s cluster and prevent microk8s traffic from going over the proxy.

EL Specific Directions

Using the same example of having a company proxy at http://corporate.proxy:3128, you would edit /etc/profile.d/http_proxy.sh and add the following lines:

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
export no_proxy=10.1.0.0/16,10.152.183.0/24,127.0.0.1

The IP Ranges specified to NO_PROXY and no_proxy are specific to the microk8s cluster and prevent microk8s traffic from going over the proxy.

In Conclusion

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 issue:

microk8s.stop
microk8s.start

to have it reload the new environment variables.

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.

Users

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:

On Ubuntu:

useradd element-demo
gpasswd -a element-demo sudo

On EL:

useradd element-demo
gpasswd -a element-demo wheel

Unpacking the Installer

Please make sure that you unpack element-enterprise-installer onto your POC 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 PoC 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, we recommend installing coturn. Instructions on how to do that are available here: https://github.com/matrix-org/synapse/blob/master/docs/turn-howto.md (Note: On EL, you can do yum install coturn -y.)

Under "Synapse Setup" in the above instructions, you'll see what to change on the config. With the installer, you can 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 how you installed the TURN server. This will allow the installer to configure synapse to use your TURN server.

A few notes on TURN servers:

SSL Certificates

For SSL Certificates, you have three options:

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 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:

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

Certificates without LetsEncrypt

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

Self-signed certificates with mkcert

The following instructions will enable you to use a tool called mkcert to generate self-signed certificates. Element nor Canonical ship this tool and so these directions are provided as one example of how to get self-signed certificates.

Ubuntu:

sudo apt-get install wget libnss3-tools

EL:

sudo yum install wget nss-tools -y

Both EL and Ubuntu:

wget
https://github.com/FiloSottile/mkcert/releases/download/v1.4.3/mkcert-v1.4.3-linux-amd64
sudo mv mkcert-v1.4.3-linux-amd64 /usr/bin/mkcert
sudo chmod +x /usr/bin/mkcert

Once you have mkcert executable, you can run:

mkcert -install
The local CA is now installed in the system trust store! ⚡️

Now, you can verify the CA Root by doing:

mkcert -CAROOT
/home/element-demo/.local/share/mkcert

Your output may not be exactly the same, but it should be similar. Once we’ve done this, we need to generate self-signed certificates for our hostnames. The following is an example of how to do it for element.local. You will need to do this for all of the aforementioned hostnames, including the fqdn.tld.

The run for the element fqdn looks like this:

mkcert element.local element 192.168.122.39 127.0.0.1

Created a new certificate valid for the following names
- "element.local"
- "element"
- "192.168.122.39"
- "127.0.0.1"

The certificate is at "./element.local+3.pem" and the key at
"./element.local+3-key.pem" ✅

It will expire on 1 May 2024

Once you have self-signed certificates, you need to copy them into the certs directory under the config directory. Certificates in the certs directory must take the form of fqdn.crt and fqdn.key.

Using our above example, these are the commands we would need to run from the installer directory: (We ran mkcert in that directory as well.)

mkdir ~/.element-onpremise-config/certs
cp element.local+3.pem  ~/.element-onpremise-config/certs/element.local.crt
cp element.local+3-key.pem  ~/.element-onpremise-config/certs/element.local.key
cp synapse.local+3.pem  ~/.element-onpremise-config/certs/synapse.local.crt
cp synapse.local+3-key.pem  ~/.element-onpremise-config/certs/synapse.local.key
cp dimension.local+3.pem  ~/.element-onpremise-config/certs/dimension.local.crt
cp dimension.local+3-key.pem  ~/.element-onpremise-config/certs/dimension.local.key
cp hookshot.local+3.pem  ~/.element-onpremise-config/certs/hookshot.local.crt
cp hookshot.local+3-key.pem  ~/.element-onpremise-config/certs/hookshot.local.key
cp local+2.pem  ~/.element-onpremise-config/certs/local.crt
cp local+2-key.pem  ~/.element-onpremise-config/certs/local.key

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 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"

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'

secrets.yml

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

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:

To configure element:

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 pointing your installation at an existing Jitsi instance, please see Setting up Jitsi With the Installer

Installation

Let’s review! Have you considered:

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 the proof of concept!

How to Install a Production Environment

Our Element Enterprise Production Installer can handle the installation of Element Enterprise into your production k8s environment.

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

Once these areas have been covered, you'll be able to install a production environment!

Hostnames/DNS

You will need hostnames for the following pieces of infrastructure:

These hostnames must resolve to the appropriate IP addresses. You should have a proper DNS server to serve these records in a production environment.

In the event that you do not have a prop

Resource Requirements

For running running in production, we support only the x86_64 architecture and recommend the following minimums:

Unpacking the Installer

Please make sure that you unpack element-enterprise-installer onto a system that has access to your k8s environment. The directory that it unpacks into will be referenced in this document as the installer directory.

You will also need to create a directory for holding the configurations for the installer. This will be referenced as the config directory going forward.

mkdir  ~/.element-onpremise-config

k8s Environments

Element Enterprise Installer allows you to either deploy directly into a kubernetes environment or to render a set of manifests for a future deployment in a kubernetes environment.

To configure your kubernetes environment for a direct deployment, you need to :

An example k8s.yml file would look like:

provider_storage_class_name: gp8-delete  # select an available storage class
ingress_annotations: ## below are expected annotations for an aws deployment
    kubernetes.io/ingress.class: alb
    alb.ingress.kubernetes.io/scheme: internet-facing
    alb.ingress.kubernetes.io/group.name: global
    alb.ingress.kubernetes.io/target-type: ip
    alb.ingress.kubernetes.io/ip-address-type: ipv4
    alb.ingress.kubernetes.io/listen-ports: '[{"HTTP": 80},{"HTTPS": 443}]'
synapse_ingress_annotations:  # below are required annotations if using the NGINX ingress controller
    nginx.ingress.kubernetes.io/proxy-body-size: "50m"
tls_managed_externally: true  # true if the certificates are managed externaly to k8s
security_context_force_uid_gid: true  # true to enable pod runAsUser and fsGroup in security context. false if it should not be used, in the case of openshift for example.
security_context_set_seccomp: true  # true to enable RuntimeDefault pod seccomp. false if it should not be used, in the case of openshift for example.
operator_namespace: <namespace to create to deploy the operator>
element_namespace: <namespace to create to deploy the element resources>
k8s_auth_context: <the k8s auth context>
out_dir: # Absolute path to the directory where to render manifests, if render mode is used
# operator_manager_limits:  # Can be used to defined upper limits if the default one are not large enough for your operator deployment
#   cpu: "2"
#   memory: 8Gi

If you do not want to deploy directly to kubernetes, but wish to render manifests instead, set all of the above mentioned variables except for k8s_auth_context and define a value for the parameter out_dir, which specifies where to write the kubernetes manifests. Further, when you go to run the installer, you need to invoke it as such:

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

Using the above syntax, you will have a set of manifests written out to out_dir that you can then deploy into your kubernetes environment.

N.B. You will need to set your ingress controller's upload size to be at least 50 Mb to match synapse's default upload size if you wish to be able to have users upload files up to 50 Mb in size. Instructions for doing this with nginx are included in the parameters.yml section below.

Postgresql Database

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

Please make note of the database hostname, database name, user, and password as you will need these to begin the installation.

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, we recommend installing coturn outside of your k8s environment. coturn must open a lot of ports to work and this can be problematic for k8s environments. Instructions on how to do that are available here: https://github.com/matrix-org/synapse/blob/master/docs/turn-howto.md (Note: On EL, you can do yum install coturn -y.)

Under "Synapse Setup" in the above instructions, you'll see what to change on the config. With the installer, you can 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 how you installed the TURN server. This will allow the installer to configure synapse to use your TURN server.

A few notes on TURN servers:

SSL Certificates

For SSL Certificates, you have three options:

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

Certificates without LetsEncrypt

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

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 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. For your Postgres server, please set the following:

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

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"

The next section pertains to certmanager. If you are not using LetsEncrypt, 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'

If you are using nginx as your ingress controller and wish to send files up to 50 Mb in size, please add these two lines to parameters.yml:

synapse_ingress_annotations:
  nginx.ingress.kubernetes.io/proxy-body-size: "50m"

secrets.yml

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

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/

You will need to uncomment and set your postgres_password field to the proper password for your database.

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:

To configure element:

For specifics on configuring permalinks for Element, please see Setting up Permalinks.

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

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 pointing your installation at an existing Jitsi instance, please see Setting up Jitsi With the Installer

Installation

Let’s review! Have you considered:

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:

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

Setting up Permalinks With the Installer

Element Extra Configurations

{
    "permalinkPrefix": "https://<element fqdn>"
}

Setting up Jitsi With the Installer

By default, our installer will give you an instance of element-web configured to use the meet.element.io Jitsi server. If you would like to specify your own Jitsi server for your element-web instance to use, please follow these directions.

Element Extra Configurations

{
      "jitsi": {
            "preferredDomain": "your.jitsi.example.org"
      }
}

replacing your.jitsi.example.org with the hostname of your Jitsi server.

Setting up Delegated Authentication With the Installer

On Element Enterprise

On the provider

Azure ADFS

Keycloak

Other SAML providers can be configured for use with Element Enterprise. Please contact Element for further information in the event that you are not using one of the above providers.

Azure ADFS

Keycloak

Setting up Group Sync with the Installer

What is Group Sync?

Group Sync allows you to use the ACLs from your identity infrastructure in order to set up permissions on Spaces and Rooms in the Element Ecosystem. Please note that the initial version we are providing only supports a single node, non-federated configuration.

General settings

Configuring the source

LDAP Servers

MS Graph (Azure AD)

Setting Up the Integration Manager With the Installer

Known Issues

The Dimension Integration Manager ships with a number of integrations that do not work in an on-premise environment. The following integrations are known to work with proper internet connectivity:

Please note that we recognise this situation is less than ideal. We will be working to improve the situation around integrations in the near future.

On the hosting machine

On element

Enabling BigBlueButton

To enable BigBlueButton integration into Element through Dimension, you should set the following variables.

Setting up GitLab, GitHub, and JIRA Integrations With the Installer

In Element Enterprise On-Premise, our GitLab, GitHub, and JIRA integrations are provided by the hookshot package. This documentation explains how to configure the installer to install hookshot and then how to interact with hookshot once installed.

Configuring Hookshot with the Installer

Enabling GitHub Integration

On GitHub

On the installation

In Element's room

Enabling GitLab integration

On GitLab

On the installation

In Element's room

{
    "instance": "<your instance name in gitlab.yml>",
    "path": "<username-or-group/repo>"
}

Enabling JIRA integration

On JIRA

Enable OAuth

The JIRA service currently only supports atlassian.com (JIRA SaaS) when handling user authentication. Support for on-prem deployments is hoping to land soon.

On the installation

In Element's room

Enabling generic webhooks integration

On the installation

In Element's room

Troubleshooting

Introduction to Troubleshooting

Troubleshooting the Element Installer comes down to knowing a little bit about kubernetes and how to check the status of the various resources. This guide will walk you through some of the initial steps that you'll want to take when things are going wrong.

install.sh problems

Sometimes there will be problems when running the ansible-playbook portion of the installer. When this happens, you can increase the verbosity of ansible logging by editing .ansible.rc in the installer directory and setting:

export ANSIBLE_DEBUG=true
export ANSIBLE_VERBOSITY=4

and re-running the installer. This will generate quite verbose output, but that typically will help pinpoint what the actual problem with the installer is.

Problems post-installation

Checking Pod Status and Getting Logs

Other Commands of Interest

Some other commands that may yield some interesting data while troubleshooting are:

Migrating From 0.6.1 to 1.0

Introduction

With the release of the 1.0 installer, we've made some changes that we think will greatly improve your experience with the installer, but which also require some changes to your 0.6.1 environment. This document will walk through the following changes:

New Configuration Directory Structure

Our on-premise installer operates on the premise that to get new updates for your environment, you download the latest version of the installer and run the installer again. Prior to the 1.0 release, this also required copying configuration files from one installer directory to the new installer directory. In 1.0, we are introducing a new configuration directory structure that will make it much simpler to download the latest installer and run it, without having to worry about moving configuration files around.

To move configuration from 0.6.1 to 1.0, please do the following:

mkdir ~/.element-onpremise-config

Now, we need to copy files from the 0.6.1 installer directory into this new configuration directory. For this example, I will assume that you have the 0.6.1 installer unpacked into ~/element-enterprise-installer-0.6.1 . Given this assumption, here is what you would need to do:

cd ~/element-enterprise-installer-0.6.1
cp parameters.yml ~/.element-onpremise-config/
cp secrets.yml ~/.element-onpremise-config/
cp -R certs ~/.element-onpremise-config/
cp -R extra-config/* ~/.element-onpremise-config/

Now you have migrated to the new configuration directory structure. Going forward, your configuration will stay in this directory.

Switching to the EMS Image Store Registry

In 1.0, we've also moved our container images to a new registry known as the EMS image store. With this move, you now only have one username and token to keep up with as opposed to the two credentials you had to manage pre-1.0.

To make the switch to the EMS Image Store Registry, you will need to contact Element and ask for an EMS Image Store user name and token. Once you have gotten these, you will need to edit secrets.yml in the configuration directory and remove these two lines:

registry_username: "myuser-2022"
registry_token: "mytoken"

and replace them with:

ems_image_store_username: "username_from_element"
ems_image_store_token: "token_from_element"

Further, if you've set the following lines in groupsync.yml, dimension.yml, and/or hookshot.yml, you will need to remove them as they are no longer used:

ems_bridges_registry_username: <ems bridges registry token name>
ems_bridges_registry_password: <ems bridges registry token password>

Wrapping Up

Once you have taken care of addressing these changes, you'll be able to run the 1.0 installer. Going forward, the syntax for running the installer will look like:

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

where the first parameter passed to install.sh is the config directory that contains your configurations.