How to Install and Configure the Element Chat App

Element is a free open source chat and messaging client that is an alternative to Discord and Slack. It implements communication protocols from the Matrix application layer using end-to-end encryption (E2EE). Formerly known as Riot and before that as Vector, Element is available as either a web application or a desktop/mobile app. This guide explains how to download and install both Element and the Matrix-Synapse communication layer. It also describes how to set up encryption and use these applications with the NGINX web server.

Before You Begin

If you have not already done so, create a Linode account and Compute Instance. See our Getting Started with Linode and Creating a Compute Instance guides.
Follow our Setting Up and Securing a Compute Instance guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access.
Register a Fully Qualified Domain Name (FQDN) for your Element service. The DNS records for the domain should be set to the IP address of your Linode. Consult Linode’s DNS Records: An Introduction and DNS Manager guides for assistance when configuring your domain.

Note
This guide is written for a non-root user. Commands that require elevated privileges are prefixed with sudo. If you are not familiar with the sudo command, see the Linux Users and Groups guide.

Advantages and Features of Element

Element offers features such as voice and group chat, video calls, and file sharing. It prioritizes security through the use of end-to-end encryption (E2EE) and cross-signed verification. Due to its open-source status and its governance by the Matrix.org Foundation, it is free from corporate influences. This means users are protected from eavesdropping, data mining, and intrusive ads.
Element also provides bridges, which allow Element users to communicate with other applications and networks such as IRC, Slack, Telegram, and Discord. Bots and widgets allow users to view or import content, such as GitHub results, Wikipedia pages, and RSS feeds.
Although the core version of Element is free for basic users, several commercial upgrades are available. Element Home is a paid service featuring more accounts and extra features, while Element Matrix Services is geared towards businesses. Element can even support large organizations and governments.

Element is based on React and uses Electron for bundling. See the Element GitHub Page to learn more, including how to develop in Element.

A Summary of the Element Installation and Configuration Process

A complete Element installation consists of the high-level steps outlined in this section. Because Element is a web client for Matrix-Synapse, you must first download and install the Matrix-Synapse software package. Element also requires a web server, such as NGINX. Although these instructions are geared towards Ubuntu installations, they are broadly applicable to most Linux distributions.

Set Up DNS Records
Download and install the Matrix-Synapse communication layer
Download, install, and configure the Element client
Install and configure the NGINX web server
Install Certbot and generate Let’s Encrypt certificates
Configure security settings for Element
Enable and test the Element client

The following sections describe each step in more detail.

Set Up DNS Records

Before connecting to Element, register a base domain for your service and set the corresponding DNS records to reference your Linode.
Create two further subdomains for the matrix and element services, each with its DNS records.
Create DNS records for the following domains and subdomains:
- example.com (general website and hosting for the Matrix services)
- example.com (general website and hosting for the Matrix services)
- matrix.example.com (Matrix/Synapse communication layer)
- element.example.com (Element web client)
  Note
  Throughout this section and the rest of the guide, replace example.com with your own domain name. See the guide for the Linode DNS Manager for more information on adding domains and DNS records.

Download and Install the Matrix-Synapse Communication Layer

Install the Matrix-Synapse service. Element depends on Matrix functionality to work properly.

Note
Synapse is the “home server” implementation of Matrix, but the two names are often used interchangeably. This guide refers to the software package as Matrix and the actual component as Matrix-Synapse to avoid confusion.

Ensure the necessary software dependencies are installed.

 sudo apt install -y lsb-release wget apt-transport-https

Download the Matrix Organization’s GPG key.

 sudo wget -O /usr/share/keyrings/matrix-org-archive-keyring.gpg https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg

Add the Matrix repository.

 echo "deb [signed-by=/usr/share/keyrings/matrix-org-archive-keyring.gpg] https://packages.matrix.org/debian/ $(lsb_release -cs) main" | sudo tee /etc/apt/sources.list.d/matrix-org.list

Use apt to install Matrix.

 sudo apt-get update -y
 sudo apt-get install matrix-synapse-py3 -y

During the installation process, Matrix asks for the name of your domain. Enter the name of the matrix subdomain.
For the Anonymous Data Statistic, choose No.
Edit the Matrix-Synapse configuration file at /etc/matrix-synapse/homeserver.yaml and set enable_registration to true.
```
 vi /etc/matrix-synapse/homeserver.yaml
```
File: /etc/matrix-synapse/homeserver.yaml
1 2 3
... enable_registration: true ...
(Optional) To limit who can register, uncomment the registration_shared_secret field in the homeserver.yaml file. Set the value of this field to a secure password and enclose it in quotation marks. This allows users to register, provided they know the password, even when enable_registration is set to false.
File: /etc/matrix-synapse/homeserver.yaml
1 2 3 4
... registration_shared_secret: "your_password" ...
(Optional) To enable additional features based on email lookups and bridging with other applications, configure an identity server for Element to use. You can use your own Linode, the default server at https://matrix.org, or a third-party service. Uncomment the default_identity_server entry inside the /etc/matrix-synapse/homeserver.yaml file and enter the address of the server. Even without an identity server, Element still functions normally and its core features are still available.

Restart Matrix-Synapse to apply the changes, and then verify its status.

 sudo systemctl restart matrix-synapse
 sudo systemctl status matrix-synapse

Matrix should indicate a status of active.

matrix-synapse.service - Synapse Matrix homeserver
Loaded: loaded (/lib/systemd/system/matrix-synapse.service; enabled; vendor preset: enabled)
Active: active (running) since Thu 2021-04-08 10:56:34 UTC; 8s ago

To allow Element and other clients to find Matrix-Synapse, create a .well-known file for it. This file must contain the hostname and port. Substitute your own domain name for example.com in the following commands.
```
 sudo mkdir -p /var/www/html/example.com/.well-known/matrix
 echo '{ "m.server": "example.com:443" }' | sudo tee /var/www/html/example.com/.well-known/matrix/server
```

Note
For more advanced installation instructions, see the Matrix-Synapse GitHub installation page. This page includes instructions for building from source and configuring Matrix-Synapse using Docker or Ansible.

Note
Earlier versions of Matrix, as well as development/beta releases, are available on the Matrix releases page.

Download, Install, and Configure the Element Client

Software packages for installing Element are found on the Element releases page. Download the tar file to your Linode using wget. The current version of Element is 1.7.24. When downloading the files, substitute the actual version you are downloading in place of 1.7.24.

Create a directory for Element inside /var/www/html and change to the directory. Substitute your domain name for example.com in the following commands.
```
 sudo mkdir -p /var/www/html/element.example.com
 cd /var/www/html/element.example.com
```

Download the Element software using wget.

 sudo wget https://github.com/vector-im/element-web/releases/download/v1.7.24/element-v1.7.24.tar.gz

Install gnupg and download the signature.

 sudo apt install -y gnupg
 sudo wget https://github.com/vector-im/element-web/releases/download/v1.7.24/element-v1.7.24.tar.gz.asc

Import the signing key for Element.

 sudo gpg --keyserver keyserver.ubuntu.com --search-keys releases@riot.im

The gpg utility confirms the key is imported.

gpg: key 74692659BDA3D940: public key "Riot Releases <releases@riot.im>" imported
gpg: Total number processed: 1
gpg: imported: 1

Use this key to validate the asc signature.

 sudo gpg --verify element-v1.7.24.tar.gz.asc

gpg confirms the signature is good.

gpg: assuming signed data in 'element-v1.7.24.tar.gz'
gpg: Signature made Mon Mar 29 12:44:56 2021 UTC
gpg: using RSA key 5EA7E0F70461A3BCBEBE4D5EF6151806032026F9
gpg: issuer "releases@riot.im"
gpg: Good signature from "Riot Releases <releases@riot.im>" [unknown]

Extract the Element software using the tar utility.
```
 sudo tar -xzvf element-v1.7.24.tar.gz
```
Create an alias for the application to make it easier to remember and set the ownership.
```
 sudo ln -s element-v1.7.24 element
 sudo chown www-data:www-data -R element
```
Change to the element directory, and create a copy of the config.sample.json file named config.json.
```
 cd element
 sudo cp config.sample.json config.json
```

Edit the base_url and server_name attributes in config.json so they reference your domain. The base_url value must reference the matrix subdomain, while server_name must indicate the base domain.

File: /var/www/html/element.example.com/element/config.json

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
{
    "default_server_config": {
        "m.homeserver": {
            "base_url": "https://matrix.example.com",
            "server_name": "example.com"
        },
        "m.identity_server": {
            "base_url": "https://example.com"
        }
    },
...
    

Install and Configure the NGINX Web Server

You must install NGINX before using Certbot. For more information about NGINX, see Linode’s How to Configure NGINX guide.

Install NGINX.
```
 sudo apt -y install nginx
```

Create files for each virtual host, corresponding to each domain, and link the directories using the ln command. Substitute the name of your domain for example.com throughout the rest of this section.

 sudo touch /etc/nginx/sites-available/{example.com,matrix.example.com,element.example.com}
 sudo ln -s /etc/nginx/sites-available/example.com /etc/nginx/sites-enabled/example.com
 sudo ln -s /etc/nginx/sites-available/matrix.example.com /etc/nginx/sites-enabled/matrix.example.com
 sudo ln -s /etc/nginx/sites-available/element.example.com /etc/nginx/sites-enabled/element.example.com

Change to the /etc/nginx/sites-available directory and add the following information to the file associated with the base domain, in this case, example.com. Use your domain for the server_name and root variables.

 cd /etc/nginx/sites-available
 vi example.com

File: /etc/nginx/sites-available/example.com

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
server {
    listen 80;
    listen [::]:80;

    server_name example.com;
    root /var/www/html/example.com;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}
    

Edit the file associated with the element subdomain, such as element.example.com, and add the following information. Use the element subdomain name throughout, and append the element directory to the end of the root field.

 vi element.example.com

File: /etc/nginx/sites-available/element.example.com

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
server {
    listen 80;
    listen [::]:80;

    server_name element.example.com;
    root /var/www/html/element.example.com/element;
    index index.html;

    location / {
        try_files $uri $uri/ =404;
    }
}
    

Edit the file corresponding to the matrix subdomain, and add the following information. Use the matrix subdomain name in the server_name and root variables.

 vi matrix.example.com

File: /etc/nginx/sites-available/matrix.example.com

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
server {
    listen 80;
    listen [::]:80;

    server_name matrix.example.com;
    root /var/www/html/matrix.example.com;
    index index.html;

    location / {
        proxy_pass http://localhost:8008;
    }
}
    

Use the NGINX syntax checker to validate the new files.

 sudo nginx -t

The output indicates that the syntax is valid.

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok
nginx: configuration file /etc/nginx/nginx.conf test is successful

Restart NGINX to apply all the configuration changes.
```
 sudo systemctl restart nginx
```

Install Certbot and Generate Let’s Encrypt Certificates

To use Element, you must enable encryption. The easiest way to do so is by using the Hypertext Transfer Protocol (HTTP). HTTP allows users to authenticate the websites they visit and ensures their data is private. A website must possess a public key certificate signed by a trusted certificate authority before it can accept HTTPS requests. This ensures the owner of the certificate operates the website in question.

You can use Let’s Encrypt to generate certificates. This service grants basic SSL/TLS certificates to websites in an automated manner. Certbot, a tool from the Electronic Frontier Foundation (EFF), automates the entire certificate-granting operation. It identifies all of the relevant domains and manages the challenge requests and the granting process. It also makes all necessary changes to the NGINX configuration.

You can install Certbot using the snap utility, which is already pre-installed on Ubuntu. Certbot uses Python to request and configure the certificate, but all necessary Python components are included in the Certbot package.

Run the following commands to update Snap and verify the current version.

 sudo snap install core
 sudo snap refresh core
 snap version

The snap version should output the following:

username@localhost:~$ /etc/nginx/sites-available$ snap version
snap    2.49.2
snapd   2.49.2
series  16
ubuntu  18.04
kernel  4.15.0-142-generic

Note
If Snap is not already installed, run the command sudo apt install snapd first.

Remove any existing Certbot packages using apt-get remove. This avoids possible conflicts.
```
 sudo apt-get remove certbot
```

Install Certbot.

 sudo snap install --classic certbot

The Snap module confirms Certbot is installed.

certbot 1.15.0 from Certbot Project (certbot-eff) installed

Configure a symbolic link to the Certbot directory using the ln command.
```
 sudo ln -s /snap/bin/certbot /usr/bin/certbot
```

Use Certbot to generate certificates for your domains. Generate all three certificates with one command by using the -d option in front of each domain. Substitute your domain names in the following command:

 sudo certbot --nginx -d example.com -d element.example.com -d matrix.example.com

You can run the client without the email address using the --register-unsafely-without-email at the end of the command:

 sudo certbot --nginx -d example.com -d element.example.com -d matrix.example.com --register-unsafely-without-email

Certbot displays updates about the requests and challenges and then confirms the domains are successfully enabled. You might be required to supply some additional information if you have never used Certbot before.

Saving debug log to /var/log/letsencrypt/letsencrypt.log
Plugins selected: Authenticator nginx, Installer nginx
Requesting a certificate for example.com and 2 more domains
Performing the following challenges:
http-01 challenge for element.example.com
http-01 challenge for example.com
http-01 challenge for matrix.example.com
Waiting for verification...
Cleaning up challenges
Deploying Certificate to VirtualHost /etc/nginx/sites-enabled/example.com
Deploying Certificate to VirtualHost /etc/nginx/sites-enabled/element.example.com
Deploying Certificate to VirtualHost /etc/nginx/sites-enabled/matrix.example.com
Redirecting all traffic on port 80 to ssl in /etc/nginx/sites-enabled/example.com
Redirecting all traffic on port 80 to ssl in /etc/nginx/sites-enabled/element.example.com
Redirecting all traffic on port 80 to ssl in /etc/nginx/sites-enabled/matrix.example.com

- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
Congratulations! You have successfully enabled <https://example.com>,
<https://element.example.com>, and <https://matrix.example.com>
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Configure Security Settings for Element

To improve the security of your Element installation and deny unauthorized traffic attempts, configure the ufw firewall. In addition to allowing NGINX traffic, port 8448 must be unblocked. You can list all eligible applications using the sudo ufw app list command.

Allow ufw to accept OpenSSH connections, and enable Nginx Full. This allows access for both IPv4 and Ipv6 requests.
```
 sudo ufw allow OpenSSH
 sudo ufw allow 'Nginx Full'
```
Unblock port 8448 in the firewall.
```
 sudo ufw allow 8448
```
Enable the firewall.
```
 sudo ufw enable
```

Verify the firewall is active and properly configured using the status command.

 sudo ufw status

Status: active
To                         Action      From

--                         ------      ----
OpenSSH                    ALLOW       Anywhere
Nginx Full                 ALLOW       Anywhere
8448                       ALLOW       Anywhere
OpenSSH (v6)               ALLOW       Anywhere (v6)
Nginx Full (v6)            ALLOW       Anywhere (v6)
8448 (v6)                  ALLOW       Anywhere (v6)

Caution
The ufw allows OpenSSH traffic. Otherwise, you could lock yourself out of your Linode.

Enable and Test the Element Client

The easiest way to ensure Element works properly is to access the site and create a login.

Enable nginx and matrix-synapse in systemctl. This ensures they are activated whenever the Linode reboots. Restart the webserver to ensure all changes are applied.
```
 sudo systemctl enable nginx
 sudo systemctl enable matrix-synapse
 sudo systemctl restart nginx
```
Using a web browser, visit the Element landing page at https://element.example.com, substituting your domain name in the URL. Element displays the following login screen.
To verify that Element can communicate with Matrix, create an account and ensure you can view the Element dashboard.

Note
If the identity server is not configured, Element displays a warning message when logging in as some of the functionalities might be unavailable. This limitation does not affect core Element features such as chat and messaging.

Learn More About Matrix-Synapse and Element

Compared to some open source projects, documentation about Element is limited. However, there are some helpful resources available.

Element provides a FAQ that answers many common questions.
The Element GitHub page also provides more information.
There is also a page explaining Element’s advanced configuration options.
Technical information about Matrix-Synapse can be found on a separate GitHub page.

More Information

You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials.

Featured

Why Linode

Get to Know Us Better

Featured

Compute

Storage

Databases

Services

Networking

Developer Tools

Featured

Solutions

Featured

Pricing

Free eBook

Community

Engage With Us

Search Results

No Results

Filters

Installing and Configuring the Element Chat Application

Before You Begin

Advantages and Features of Element

A Summary of the Element Installation and Configuration Process

Set Up DNS Records

Download and Install the Matrix-Synapse Communication Layer

Download, Install, and Configure the Element Client

Install and Configure the NGINX Web Server

Install Certbot and Generate Let’s Encrypt Certificates

Configure Security Settings for Element

Enable and Test the Element Client

Learn More About Matrix-Synapse and Element

More Information

Your Feedback Is Important