synapse_ubucon_workshop.md

Step 0: SSH into the server

You will be provided with a domain name looking like xxxxx.ubucon.abolivier.bzh, which points to your dedicated VPS. To access the server's command line, run ssh ubuntu@xxxxx.ubucon.abolivier.bzh from a terminal (or connect with your favourite SSH client with the user ubuntu), and use the password ubucon2019.

Step 1: Install the Matrix.org repository

wget -qO - https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg | sudo apt-key add -
sudo add-apt-repository "deb https://packages.matrix.org/debian/ bionic main"

Step 2: Install Synapse

sudo apt install sqlite3 matrix-synapse

During the installation, you will be asked for a server name; just paste the domain name you've been given for the server.

Going further

Alternative ways to install Synapse are listed at https://github.com/matrix-org/synapse/blob/master/INSTALL.md

This workshop uses SQLite as Synapse's database backend for convenience, but this is not advised for production setups. Instead consider using PostgreSQL, see https://github.com/matrix-org/synapse/blob/master/docs/postgres.md

Step 3: Configure Synapse

Edit the file /etc/matrix-synapse/homeserver.yaml with your favourite command-line editor.

In the listeners section, uncomment the following lines:

  - port: 8448
    type: http
    tls: true
    resources:
      - names: [client, federation]

Uncomment the lines tls_certificate_path and the tls_private_key_path. On their values, you probably want to replace SERVERNAME with the domain name you've been given for the sever.

Uncomment the line enable_registration and set its value to true.

In the acme section, change the value for the line enabled to true, and comment out the line domain.

Additionally, in this same acme section, change the value for the line port to 8888 (this is specific to the setup for this workshop).

Apply the configuration by running sudo systemctl restart matrix-synapse to restart Synapse. Follow the Synapse logs by running sudo journalctl -fu matrix-synapse to make sure Synapse starts correctly (feel free to call one of the speakers if it doesn't). Exit the logs with Ctrl+C.

You can check that Synapse is running correctly and is listening by opening a browser tab to https://{domain}:8448 (with {domain} being the domain name you've been given for the server). You should see a page telling you that "Synapse is running".

Step 4: Use Synapse and Riot to federate

Open a browser tab to https://{domain} (with {domain} being the domain name you've been given for the server) to open Riot. Create a new account (Riot should already be configured to use the homeserver we've installed), then, once logged in, click on the "Explore" button on the top left corner of the window.

Paste #ubucon2019:abolivier.bzh in the text field, then hit Enter.

Congratulations! You're now talking to other federated homeservers with your brand new Synapse homeserver! :)