---
# System prepended metadata

title: Matrix synapse

---

# Matrix synapse
Author: Xiaoming Guo
## Introduction
Matrix is an ambitious new ecosystem for open federated Instant Messaging and VoIP. The basics you need to know to get up and running are:

Everything in Matrix happens in a room. Rooms are distributed and do not exist on any single server. Rooms can be located using convenience aliases like #matrix:matrix.org or #test:localhost:8448.
Matrix user IDs look like @matthew:matrix.org (although in the future you will normally refer to yourself and others using a third party identifier (3PID): email address, phone number, etc rather than manipulating Matrix user IDs)
The overall architecture is:
```
                  How data flows between clients
                  ==============================

      { Alice }                                      
    ^          |                                    
    |  events  |  Client-Server API                 
    |          V                                    
+------------------+                            
|                  |--------->
|   homeserver     |  events  { Bob }
|                  |<---------
+------------------+    
```
```
                  How data flows between clients
                  ==============================

      { Alice }                                        { Bob }
    ^          |                                    ^          |
    |  events  |  Client-Server API                 |  events  |
    |          V                                    |          V
+------------------+                            +------------------+
|                  |---------( HTTPS )--------->|                  |
|   homeserver     |                            |   homeserver     |
|                  |<--------( HTTPS )----------|                  |
+------------------+      Server-Server API     +------------------+
                       History Synchronisation
                           (Federation)
```
### 1:1 voice or video call
```
                     1:1 call is peer to peer
     { Alice }  <---------------------------------->   { Bob }
    ^          |                                    ^          |
    |  events  |  Client-Server API                 |  events  |
    |          V                                    |          V
+------------------+                            +------------------+
|                  |---------( HTTPS )--------->|                  |
|   homeserver     |                            |   homeserver     |
|                  |<--------( HTTPS )----------|                  |
+------------------+      Server-Server API     +------------------+
                       History Synchronisation
                           (Federation)
```
### Conference voice or video call
```
      { Alice }  <-------------------------------------       
          ^                                            |
          |                                            |
          V                                            V
+------------------+                             +------------------+      
|                  | <------- { Bob } ---------> |                  |
|   Jisti Server   |                             |    homeserver    |
|                  | <------- { Carol } -------> |                  |
+------------------+                             +------------------+

```
Github: https://github.com/matrix-org/synapse
Clients: https://matrix.org/clients/ or https://matrix.org/docs/projects/try-matrix-now/
## Install on Ubuntu virtual machine
### System requirements
* POSIX-compliant system (tested on Linux & OS X)
* Python 3.5.2 or later, up to Python 3.8.
* At least 1GB of free RAM 
### Install Ubuntu 18.04 virtual machine on virtualbox
* Install virtualbox on your host machine
* Download the ubuntu 18.04 image
* Create a new ubuntu 18.04 virtual machine via virtualbox UI
* After the ubuntu virtual machine gets created, install openssh-server and necessary packages
### Prerequisites
* https://github.com/matrix-org/synapse/blob/master/INSTALL.md#debianubunturaspbian
    ```
    sudo apt install openssh-server python-pip virtualenv \
        build-essential python3-dev libffi-dev \
        python3-pip python3-setuptools sqlite3 \
        libssl-dev python3-virtualenv libjpeg-dev libxslt1-dev
    ```
* Choose the DNS names
  * ubuntu.com (general website, and for hosting a .well-known path to advertise Matrix)
  * synapse.ubuntu.com (Synapse)
### Install Nginx
* `sudo apt-get update && sudo apt -y install nginx`
* Setup reverse proxy to synapse server
    ```
    sudo unlink /etc/nginx/sites-enabled/default
    
    sudo cat > /etc/nginx/sites-available/synapse.ubuntu.com << EOF
    server {
       listen 8108;
       listen [::]:8108;

       location / {
               proxy_pass http://localhost:8008;
       }
    }
    EOF
    
    sudo systemctl restart nginx
    ```

* (Skip) Enable TLS via LetsEncrypt on nginx 
    ```
    sudo apt install -y python3-certbot-nginx
    sudo certbot --nginx -d ubuntu.com -d synapse.ubuntu.com
    ```
### Setup matrix
#### Install matrix
```
mkdir -p ~/synapse
virtualenv -p python3 ~/synapse/env
source ~/synapse/env/bin/activate
pip install --upgrade pip
pip install --upgrade setuptools
pip install matrix-synapse
```
Sample output:
```
(env) synapse-vm@synapsevm-VirtualBox:~$ pip install --upgrade pip
Requirement already up-to-date: pip in ./synapse/env/lib/python3.6/site-packages (20.0.2)
(env) synapse-vm@synapsevm-VirtualBox:~$ pip install --upgrade setuptools
Requirement already up-to-date: setuptools in ./synapse/env/lib/python3.6/site-packages (46.1.3)
(env) synapse-vm@synapsevm-VirtualBox:~$ pip install matrix-synapse
Collecting matrix-synapse
  Downloading matrix-synapse-1.12.0.tar.gz (2.1 MB)
     |████████████████████████████████| 2.1 MB 2.0 MB/s
  Installing build dependencies ... done
  Getting requirements to build wheel ... done
    Preparing wheel metadata ... done
Collecting bcrypt>=3.1.0
  Downloading bcrypt-3.1.7-cp34-abi3-manylinux1_x86_64.whl (56 kB)
     |████████████████████████████████| 56 kB 2.3 MB/s
Collecting netaddr>=0.7.18
  Downloading netaddr-0.7.19-py2.py3-none-any.whl (1.6 MB)
...
Successfully installed Automat-20.2.0 Jinja2-2.11.1 MarkupSafe-1.1.1 PyHamcrest-2.0.2 Twisted-20.3.0 attrs-19.3.0 bcrypt-3.1.7 bleach-3.1.4 canonicaljson-1.1.4 certifi-2019.11.28 cffi-1.14.0 chardet-3.0.4 constantly-15.1.0 cryptography-2.8 daemonize-2.5.0 frozendict-1.2 hyperlink-19.0.0 idna-2.9 importlib-metadata-1.6.0 incremental-17.5.0 jsonschema-3.2.0 matrix-synapse-1.12.0 msgpack-1.0.0 netaddr-0.7.19 phonenumbers-8.12.0 pillow-7.0.0 prometheus-client-0.7.1 pyasn1-0.4.8 pyasn1-modules-0.2.8 pycparser-2.20 pymacaroons-0.13.0 pynacl-1.3.0 pyopenssl-19.1.0 pyrsistent-0.16.0 pyyaml-5.3.1 requests-2.23.0 service-identity-18.1.0 signedjson-1.1.1 simplejson-3.17.0 six-1.14.0 sortedcontainers-2.1.0 treq-20.3.0 typing-extensions-3.7.4.1 unpaddedbase64-1.1.0 urllib3-1.25.8 webencodings-0.5.1 zipp-3.1.0 zope.interface-5.0.1
```
#### Generate config YAML
After the intallation, you need to generate the configuration file. Modify the homeserver.yaml if necessary.
```
cd ~/synapse
python -m synapse.app.homeserver --server-name synapsevm.demo.com --config-path homeserver.yaml --generate-config --report-stats=yes
    
(env) synapse-vm@synapsevm-VirtualBox:~/synapse$ ll
total 84
drwxrwxr-x  3 synapse-vm synapse-vm  4096 Mar 29 22:03 ./
drwxr-xr-x 15 synapse-vm synapse-vm  4096 Mar 29 22:03 ../
drwxrwxr-x  6 synapse-vm synapse-vm  4096 Mar 29 17:17 env/
-rw-rw-r--  1 synapse-vm synapse-vm 63785 Mar 29 20:21 homeserver.yaml
-rw-rw-r--  1 synapse-vm synapse-vm  1123 Mar 29 20:21 synapsevm-VirtualBox.log.config
-rw-rw-r--  1 synapse-vm synapse-vm    59 Mar 29 20:21 synapsevm-VirtualBox.signing.key
```
#### Start homeserver
To start a new homeserver, run the following:
```
cd ~/synapse
source env/bin/activate # You do not need to run this if you already activated the virtual env
synctl start
```
Now you should be able to access the synapse server from browser by using the `http://<vm-ip>:<8001>
![](https://i.imgur.com/RxeMA6V.png)
#### Regsiter user
```
cd ~/synapse
source env/bin/activate # You do not need to run this if you already activated the virtual env
register_new_matrix_user -c homeserver.yaml http://localhost:8008
```
### Setup Jitsi
**Note**: I am doing Jitsi on a seperate vm
https://github.com/jitsi/jitsi-meet/blob/master/doc/quick-install.md
#### Add the Jitsi package repository
```
echo 'deb https://download.jitsi.org stable/' >> /etc/apt/sources.list.d/jitsi-stable.list
wget -qO -  https://download.jitsi.org/jitsi-key.gpg.key | sudo apt-key add -
```
#### Install Jitsi
```
# Ensure support is available for apt repositories served via HTTPS
sudo apt-get install apt-transport-https

# Retrieve the latest package versions across all repositories
sudo apt-get update

# Perform jitsi-meet installation
sudo apt-get -y install jitsi-meet
```
During the installation, you will be asked to enter the hostname of the Jitsi Meet instance. If you have a FQDN for the instance already set up in DNS, enter it there. If you don't have a resolvable hostname, you can enter the IP address of the machine (if it is static or doesn't change).




## References
* https://matrix.org/blog/2020/04/06/running-your-own-secure-communication-service-with-matrix-and-jitsi



