Matrix

The IRC of the future! Here is how to install it for a domain, assuming Debian or Ubuntu.

DNS

Create a 'matrix' subdomain A record for the domain, e.g. matrix.example.com. There are SRV records you can set up for clients to figure out federation, but it's easier to use well-known URLs instead (see below).

Install Synapse

Synapse is the Matrix server, which is a Python 3 daemon using the Twisted libraries. Add the upstream apt repositories:

sudo apt install -y apt-transport-https
sudo wget -O /etc/apt/trusted.gpg.d/matrix-org-archive-keyring.gpg \
   https://packages.matrix.org/debian/matrix-org-archive-keyring.gpg
echo "deb https://packages.matrix.org/debian/ $(lsb_release -cs) main" \
   | sudo tee /etc/apt/sources.list.d/matrix-org.list
sudo apt update
sudo apt install matrix-synapse-py3

Web configuration

There are two steps to this, unless we fiddle about using SRV DNS records.

Well-known URLs

First, we need to add two .well-known URLs to the root domain's web (if any), which need to return JSON content. In the .well-known/matrix directory, create a file called "server" with:

{"m.server": "matrix.example.com:443"}

and a file called "client" with:

{"m.homeserver": {"base_url": "https://matrix.example.com"}}

Then amend the web config to add these headers:

<VirtualHost *:443>
  ServerName example.com
  SSLEngine on
  # ...
  <Directory "/path/to/www/.wellknown/matrix">
    Header set Content-Type "application/json"
    Header set Access-Control-Allow-Origin "*"
  </Directory>
</VirtualHost>

Reverse Proxy

Second, Point Apache or nginx at it as a reverse proxy to localhost:8008 and configure for SSL on port 443. Make sure the .well-known URLs resolve and have useful headers for JSON.

<VirtualHost *:443>
  ServerName matrix.example.com 
  SSLEngine on
  # ... 
  AllowEncodedSlashes NoDecode
  ProxyPass /_matrix http://localhost:8008/_matrix nocanon
  ProxyPassReverse /_matrix http://localhost:8008/_matrix
  ProxyPass /_synapse/client http://localhost:8008/_synapse/client nocanon
  ProxyPassReverse /_synapse/client http://localhost:8008/_synapse/client
</VirtualHost>

Database

Synapse can use SQLite, but it's best to use PostgreSQL in production. Create a user and empty database on PostgreSQL. For some (possibly dumb) reason, Synapse requires old C style collation, which means we have to use template0:

createuser -SDRP <dbuser>
createdb -T template0 --lc-ctype=C --lc-collate=C -E UTF-8 -O <dbuser> <dbname>

Configuration

Edit /etc/matrix-synapse/homeserver.yaml to configure URL, database and SMTP server details:

# Protect the configuration directory: chmod 700 /etc/matrix-synapse
public_baseurl: https://matrix.example.com/
database:
  name: psycopg2
    args:
      user: <dbuser>
      password: <password>
      database: <dbname>
      host: <dbhost>
      cp_min: 5
      cp_max: 10
# Generate secret strings with something like: pwgen -s 34 1
registration_shared_secret: <a long random string>
macaroon_secret_key: <a different long random string>
suppress_key_server_warning: true
email:
  smtp_host: mail.example.com
  smtp_port: 25
  smtp_user: <user>
  smtp_pass: <password>
  require_transport_security: true
  notif_from: "Matrix Server at example.com <noreply-matrix@example.com>"

Registering new users

The Debian package disables online user registration by default; use the register_new_matrix_user command from the cli, or enable it in the configuration. Set the registration_shared_secret to something long, and use:

register_new_matrix_user -u <username> -c /etc/matrix-synapse/homeserver.yaml https://matrix.example.com

References

• Matrix.org documentation, "Installing Synapse"