Tutorials How to install Matrix Synapse Home Server

How to install Matrix Synapse Home Server

Matrix logo

This guide will help you install and get started with Matrix and its reference home server Synapse. The instructions and example commands are intended to be used on a cloud server running either CentOS 7, Debian 9, or Ubuntu 16

What is Matrix?

Matrix is an open standard for decentralised communication, which securely distributes persistent chatrooms over an open federation of servers preventing any single points of control or failure.

Matrix provides simple HTTP APIs and open source reference implementations to create a common fabric to interconnect existing communication islands. Some of the use cases include creating and managing fully distributed conversations, enabling WebRTC VoIP and video calls using Matrix signalling, and synchronising history across all clients in real-time.

1. Deploy a cloud server

If you have not already registered with UpCloud, you should begin here to get signed up. Take a moment to create an account after which you can easily deploy your own cloud servers.

Once you have signed up, log into your UpCloud control panel and deploy a server.

Synapse requires a POSIX-compliant system, such as the aforementioned Linux distributions, Python 2.7 installed, and at least 1GB of free RAM to be able to join large public rooms such as the #matrix:matrix.org.

Deploy a new cloud instance for hosting the Matrix home server using one of the tested Linux operating systems to an availability zone of your choosing. You can find in-depth instructions on all of the configuration options at the guide for how to deploy a server.

2. Installing prerequisites

When you have a server up and running, use the commands below appropriate to your system to install the required packages and libraries.

For Ubuntu 16 and Debian 9 systems, install the prerequisites with the following command.

sudo apt-get install build-essential python2.7-dev libffi-dev \
  python-pip python-setuptools sqlite3 \
  libssl-dev python-virtualenv libjpeg-dev libxslt1-dev

On CentOS 7, you can fulfil the requirements with the installs below. You will also need to enable access to the required ports and services at the firewall.

sudo yum install libtiff-devel libjpeg-devel libzip-devel freetype-devel \
  lcms2-devel libwebp-devel tcl-devel tk-devel \
  python-virtualenv libffi-devel openssl-devel
sudo yum groupinstall "Development Tools"
sudo firewall-cmd --permanent --add-service https
sudo firewall-cmd --permanent --add-service http
sudo firewall-cmd --permanent --add-port=8448/tcp
sudo firewall-cmd --reload

With the prerequisites sorted, you can continue installing Synapse.

3. Installing Synapse home server

Synapse is the Matrix reference implementation of a “home server” written by the Matrix core development team. It is intended as a showcase of the Matrix concept to demonstrate the spec in the context of a codebase. It lets you easily run your own home server and generally helps to bootstrap the Matrix ecosystem.

The home servers are used as an access point for clients to connect to the Matrix network. They store the users’ personal chat history and account information in a similar fashion as an IMAP/SMTP server would. Like email, you can run your own Matrix home server to keep personal control and ownership of your communications and history or use one of the hosted Matrix services. Matrix has no single point of control or mandatory service provider.

Matrix network

To prepare the system, set up a new virtual environment under ~/.synapse using the commands below or choose a different directory by replacing the ~/.synapse in the commands with the folder you wish to store the server files.

virtualenv -p python2.7 ~/.synapse
source ~/.synapse/bin/activate

Check that the following packages are installed and up to date.

pip install --upgrade pip virtualenv six packaging appdirs

Then use pip to install and upgrade the setup tools as well as the Synapse server itself.

pip install --upgrade setuptools
pip install https://github.com/matrix-org/synapse/tarball/master

This installs the Synapse home server along with its libraries.

If you run into problems installing the Synapse home server, Matrix has outlined some helpful troubleshooting tips at the Synapse GitHub page.

4. Configuring synapse

Before Synapse can be started, you will need to generate a configuration file that defines the server settings.

Run the following commands in your Synapse virtual environment. Replace the <my.domain.name> with your server name, but note that the name cannot be changed later without reinstalling the home server. Also, choose whether you wish to allow Synapse to report statistics by entering either --report-stats=yes or no.

source ~/.synapse/bin/activate
cd ~/.synapse
python -m synapse.app.homeserver \
  --server-name <my.domain.name> \
  --config-path homeserver.yaml \
  --generate-config \
A config file has been generated in 'homeserver.yaml' for server name '<my.domain.name>' with corresponding SSL keys and self-signed certificates. Please review this file and customise it to your needs.
If this server name is incorrect, you will need to regenerate the SSL certificates

Once Synapse has finished generating the required settings, you should see a confirmation like in the example output above.

5. Configuring a reverse proxy with nginx

Matrix recommends setting up a reverse proxy, such as nginx, Apache or HAProxy, in front of your Synapse server. This is intended to allow Matrix clients to use the common HTTPS port 443. Using a proxy in addition to the 8448 in the default configuration retains server-to-server connectivity while simplifying client connections.

Change the home server configuration to listen to the localhost address for the port 8008. Open the homeserver.yaml file for edit.

vi ~/.synapse/homeserver.yaml

Find the following segment and set the binding address to and forward flag to true as shown below.

  # Unsecure HTTP listener,
  # For when matrix traffic passes through loadbalancer that unwraps TLS.
  - port: 8008
    tls: false
    bind_addresses: ['']
    type: http

    x_forwarded: true

Save the file and exit.

Next, install nginx itself.

On Debian 9 and Ubuntu 16 systems, simply run the following command.

sudo apt install nginx

CentOS 7 systems will require you to first install the Extra Packages for Enterprise Linux (EPEL) and then nginx afterwards.

sudo yum install epel-release
sudo yum update
sudo yum install nginx

Create a configuration file for the proxy functionality.

sudo vi /etc/nginx/conf.d/matrix.conf

Enter the following to enable the proxy with SSL termination. Replace the <my.domain.name> with your domain in the server name and SSL certificates.

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name <my.domain.name>;

    ssl on;
    ssl_certificate /root/.synapse/<my.domain.name>.tls.crt;
    ssl_certificate_key /root/.synapse/<my.domain.name>.tls.key;

    location / {
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;

Once done save the file and exit the editor.

Then start and enable nginx.

sudo systemctl start nginx
sudo systemctl enable nginx

That’s all you need for configuring a Synapse home server. Continue below by optionally installing a trusted SSL certificate using Let’s Encrypt, or skip straight to starting the server and creating your first user.

6. Replacing the self-signed certificates (Optional)

Synapse includes self-signed SSL certificates by default which can be used to securely test the system, but for a more production orientated setup, you might wish to obtain keys from a trusted Certificate Authority such as Let’s Encrypt.

Install the Let’s Encrypt’s Certbot client, depending on your Linux distribution, following the instructions below.

On Ubuntu 16, you’ll need to do is install the common software properties and add the Certbot repository. Afterwards, you can install the Certbot client now available through the package manager.

sudo apt-get update
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:certbot/certbot
sudo apt-get update
sudo apt-get install python-certbot-nginx

Debian 9 requires you to include the Jessie backports repository in your sources to be able to install the Certbot client.

sudo apt-get install python-certbot-nginx

With CentOS 7 the Certbot client is available through the extra packages repository.

sudo yum install epel-release
sudo yum update
sudo yum install python2-certbot-nginx

With the client installed, you can obtain certificates using the certonly command together with the --standalone plugin. Include at least one domain name by replacing the <my.domain.name> with yours.

On Debian, use the Certbot client as shown in the example below.

sudo certbot certonly --authenticator standalone --pre-hook "nginx -s stop" --post-hook "nginx" -d <my.domain.name>

CentOS and Ubuntu systems use the same simpler command like below.

sudo certbot --nginx certonly -d <my.domain.name>

The command starts an interactive configuration script that asks a couple of questions to help with managing certificates.

  1. On the first installation on any specific host, you’ll need to enter a contact email.
  2. Then go through the Let’s Encrypt Terms of Service and select Agree if you accept the terms and wish to use the service.
  3. Choose whether you wish to share your email address with the Electronic Frontier Foundation (EFF) for updates on their work.

If the client was successful at obtaining a certificate you can find a confirmation and certificate expiration date at the end of the client output.

In case you are having problems with the client, make sure you are trying to register a domain or subdomain that currently resolves to your server as DNS configurations might take a moment to propagate. Also, check that you are running the command with admin privileges.

When the certificates have been issued successfully, add them in the Synapse home server settings by editing the homeserver.yaml file in the server folder.

sudo vi /etc/nginx/conf.d/matrix.conf

The certificates issued by Let’s Encrypt are saved under the directory indicated above. Again, replace the <my.domain.name> with the domain name the certificates were issued for. Then save the settings and exit the editor.

server {
    listen 443 ssl;
    listen [::]:443 ssl;
    server_name <my.domain.name>;

    ssl on;
    ssl_certificate /etc/letsencrypt/live/<my.domain.name>/cert.pem;
    ssl_certificate_key /etc/letsencrypt/live/<my.domain.name>/privkey.pem;

    location / {
        proxy_pass http://localhost:8008;
        proxy_set_header X-Forwarded-For $remote_addr;

Save the file again and exit the text editor.

You should also include the trusted certificates in the home server file. Open the homeserver.yaml file and find the two following two certificate paths. Set the path to point to the Let’s Encrypt certificates as you did in the nginx SSL settings.

vi ~/.synapse/homeserver.yaml
tls_certificate_path: "/etc/letsencrypt/live/<my.domain.name>/cert.pem"
tls_private_key_path: "/etc/letsencrypt/live/<my.domain.name>/privkey.pem"

Then restart nginx to enable the new certificates.

sudo systemctl restart nginx

You can find out more about the Let’s Encrypt client including how to automate the certificate renewal in our article for how to install Let’s Encrypt on nginx.

7. Registering a new user

Now that Synapse is installed, you should add a new user as an admin to be able to configure chat rooms and web client settings. First, make sure you are in the home server virtual environment, then start the server and register a new user to the localhost.

source ~/.synapse/bin/activate
synctl start
register_new_matrix_user -c homeserver.yaml http://localhost:8008

This starts an interactive user configuration, enter the desired username and password, then select yes to enable administration priveledges.

New user localpart [root]: <username>
Password: <password>
Confirm password: <password>
Make admin [no]: <yes|no>
Sending registration request...

That is it, you should now be able to log into your Synapse home server with the user credentials you just added.

8. Logging into Matrix

Users have the ability to connect to a Matric home server using one or more Matrix clients.

The home server includes a simple Matrix client by default which you can use for testing. Alternatively, you can use the Riot web client, which has a polished and easy to use user interface, if you installed CA trusted certificates.


Synapse default client login

If you installed trusted certificates using Let’s Encrypt, you can connect to your home server using a public client such as Riot.


Riot web client login

Whichever client you choose to use, enter your server details for home and identity servers.

Home server URL: https://<my.domain.name>
Identity server URL: https://<my.domain.name>

Then sign in with the username and password you just created on your own home server. Other client applications can be found at the Matrix documentation page.

9. Creating a room

Next, you might wish to create a new room. In Matrix, everything happens in rooms which are distributed and do not exist on any single server. Rooms can be identified and located using aliases such as #matrix:matrix.org or #test:localhost:8008.

Click either the Create room button in the Synapse default client or the plus icon at the bottom left corner of the Riot web client. Give your room a name, and with the Synapse client, you can also make the room public. Then hit enter to save the name and join the new room.

The rooms can be used just as any communication channel, but Matrix is intended to be much more capable than a simple text chat. The basic implementation of the Synapse home server and web client are just examples of how the Matrix network can be utilised. There are already a number of other options for home servers with many different use cases. You can find more publicly available application servers in the Matrix projects documentation.

All done!

Congratulations, you have now successfully deployed and configured your first Matrix home server using Synapse.

If you would like to try out different clients, Weechat Matrix plugin allows logging in even on the command line, while Riot is also available on Android and iOS. Alternatively, those with the technical know-how can always write their own client using one of the Matrix SDKs.

Matrix presents a tonne of potential for secure communication for anything from group chat rooms, VoIP and video calls, to exchange of persistent data between devices and services in the Internet of Things. Feel free to experiment with the existing servers and clients or begin developing your own!

5 thoughts on “How to install Matrix Synapse Home Server

  1. Thank you for this guide!
    It was really helpful, even though I ran Nginx in a way that didn’t fit the guide it was easy enouhg to follow through.

    1. Hi Sami, thanks for the comment, we’ll get the guide updated to reflect the new requirement.

  2. Hey Janne,

    this Tutorial is not up to date due the python change from 2.7 to 3.5 in synapse…

    could you please update this awesome guide?


    1. Hi Kevin, thanks for the comment. The guide is in need of an update and we’ll get on it soon!

Leave a Reply

Your email address will not be published. Required fields are marked *


Helsinki (HQ)

In the capital city of Finland, you will find our headquarters, and our first data centre. This is where we handle most of our development and innovation.


London was our second office to open, and a important step in introducing UpCloud to the world. Here our amazing staff can help you with both sales and support, in addition to host tons of interesting meetups.


Seattle is our 4th and latest office to be opened, and our way to reach out across the pond to our many users in the Americas.


Singapore was our 3rd office to be opened, and enjoys one of most engaged and fastest growing user bases we have ever seen.