Jon's Wiki
Difference between revisions of "Matrix"

Difference between revisions of "Matrix"

From Jon's Wiki
(Created page with "The IRC of the future! == Installing for a domain == Create a 'matrix' subdomain A record for the domain, e.g. matrix.example.com then add a .well-known to https://example.c...")
 
 
(8 intermediate revisions by the same user not shown)
Line 1: Line 1:
−
The IRC of the future!
+
The IRC of the future! Here is how to install it for a domain, assuming Debian or Ubuntu.
  
−
== Installing for a domain ==
+
== DNS ==
  
−
Create a 'matrix' subdomain A record for the domain, e.g. matrix.example.com then add a .well-known to https://example.com/.well-known/matrix/server that returns MIME type application/json with the following:
+
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 ==
−
  "m.server": "matrix.example.com:443"
 
−
}
 
  
 +
Synapse is the Matrix server, which is a Python 3 daemon using the Twisted libraries. Add the upstream apt repositories:
  
 +
apt install -y apt-transport-https
 +
wget -O /etc/apt/trusted.gpg.d/matrix-org-archive-keyring.gpg \
 +
    <nowiki>https://</nowiki>packages.matrix.org/debian/matrix-org-archive-keyring.gpg
 +
echo "deb <nowiki>https://</nowiki>packages.matrix.org/debian/ $(lsb_release -cs) main" \
 +
    > /etc/apt/sources.list.d/matrix-org.list
 +
apt update
 +
apt install matrix-synapse-py3
  
−
See: https://matrix.org/docs/guides/installing-synapse
+
== Web configuration ==
 +
 
 +
There are two steps to this.
 +
 
 +
=== Well-known URLs ===
 +
 
 +
This step is not required if DNS SRV records are used instead. Add two .well-known URLs to the root domain's web, which need to return JSON content. In the <tt>.well-known/matrix</tt> directory, create a file called "server" with:
 +
{"m.server": "matrix.'''example.com''':443"}
 +
 +
and a file called "client" with:
 +
{"m.homeserver": {"base_url": "<nowiki>https://</nowiki>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.
 +
<VirtualHost *:443>
 +
  ServerName matrix.'''example.com'''
 +
  SSLEngine on
 +
  ''# ...''
 +
  AllowEncodedSlashes NoDecode
 +
  ProxyPass /_matrix <nowiki>http://</nowiki>localhost:8008/_matrix nocanon
 +
  ProxyPassReverse /_matrix <nowiki>http://</nowiki>localhost:8008/_matrix
 +
  ProxyPass /_synapse/client <nowiki>http://</nowiki>localhost:8008/_synapse/client nocanon
 +
  ProxyPassReverse /_synapse/client <nowiki>http://</nowiki>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 <tt>/etc/matrix-synapse/homeserver.yaml</tt> to configure URL, database and SMTP server details:
 +
 
 +
''# Protect the configuration directory: chmod 700 /etc/matrix-synapse''
 +
public_baseurl: <nowiki>https://</nowiki>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 <tt>register_new_matrix_user</tt> command from the cli, or enable it in the configuration. Set the <tt>registration_shared_secret</tt> to something long, and use:
 +
 
 +
register_new_matrix_user -u ''<username>'' -c /etc/matrix-synapse/homeserver.yaml <nowiki>https://</nowiki>matrix.'''example.com'''
 +
 
 +
== References ==
 +
 
 +
* Matrix.org documentation, [https://matrix.org/docs/guides/installing-synapse "Installing Synapse"]

Latest revision as of 21:41, 24 February 2022

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: 

apt install -y apt-transport-https
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" \
   > /etc/apt/sources.list.d/matrix-org.list
apt update
apt install matrix-synapse-py3

Web configuration

There are two steps to this.

Well-known URLs

This step is not required if DNS SRV records are used instead. Add two .well-known URLs to the root domain's web, 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. 

<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

Retrieved from "https://wiki.jon.geek.nz/index.php?title=Matrix&oldid=2454"