Matrix Synapse installieren

Der Matrix Server Synapse, der sogenannte 'Homeserver', ist aktuell die einzige vollständige serverseitige Implementierung des Matrix-Protokolls.

Work in Progress

Leider funktioniert die Server-zu-Server-Kommunikation von Synapse hinter dem Apache-Proxy mit den genannten Rewrite-Rules nicht. Bitten Sie dazu den Service, Ihren Apache VHost individuell für den Matrix Server anzupassen.

Synapse wird bei Hostsharing als eigener Daemon betrieben. Der Betrieb ist im Shared Hosting anmelde- und kostenpflichtig. Daher empfehlen wir für den Betrieb einen Managed Server.

Diese Anleitung beschreibt, wie man den Matrix-Homeserver Synapse auf der Managed Hosting Plattform von Hostsharing installieren kann. Dabei sind die User-IDs nach dem Schema @user:beispiel.de aufgebaut, der Homeserver an sich ist unter matrix.beispiel.de erreichbar.

Vorbereitungen

Mit Hilfe von HSAdmin werden angelegt:

1. Ein User als Service-User mit /bin/bash als Shell, zum Beispiel Beispiel: xyz00-matrix
2. Eine Domain mit xyz00-matrix als Domain-Administrator, zum Beispiel matrix.beispiel.de
3. Einen Postgresql-User xyz00_matrixuser mit Passwort meinPasswort
4. Eine Postgresql-Datenbank xyz00_matrixdb mit Datenbank-Owner xyz00_matrixuser

Verwendeter IP-Port für den Server-Dienst:

1. Synapse: localhost:32801

Installation von Synapse

Installationsanleitung basierend auf https://matrix-org.github.io/synapse/latest/setup/installation.html#installing-as-a-python-module-from-pypi

Auf Debian Buster muss ein neueres Python, z.B. Python 3.9 installiert werden, siehe Eigenes Python mit pyenv installieren.

Als User xyz00-matrix" ein Python3 virtualenv mit Python 3.9 erstellen

 mkdir -p ~/synapse
 cd ~/synapse
 pipenv install --python 3.9.18

Synapse und Postgres-Dependencies installieren

 cd ~/synapse
 pipenv shell
 pipenv install matrix-synapse[postgres]

Initiale Konfiguration mit richtigem server-name "beispiel.de" generieren, außerdem im laufenden Betrieb keine Statistiken an Matrix.org senden

 cd ~/synapse
 pipenv run python -m synapse.app.homeserver --server-name beispiel.de --config-path homeserver.yaml --generate-config --report-stats=no

Konfiguration von Synapse

In die initial generierte Konfiguration muss noch die Port- und Datenbank-Konfiguration eingetragen werden:

Port: Innerhalb der listener-section den Port 8008 auf 32801 (wie initial definiert) ändern, alles andere beibehalten:

    - port: 32801
      tls: false
      bind_addresses: ['::1', '127.0.0.1']
      type: http
      x_forwarded: true

Postgres-Datenbank:

    database:
      # The database engine name
      name: "psycopg2"
      # Arguments to pass to the engine
      args:
        host: "localhost"
        database: "xyz00_matrixdb"
        user: "xyz00_matrixuser"
        password: "meinPasswort"
        cp_min: 5
        cp_max: 10

Starten der Dienste

Der Synapse-Dienst wird hier als Service-Unit im SystemD des Users eingetragen.

Lege dazu die folgende Datei an: ~/.config/systemd/user/synapse.service mit dem Inhalt:

 [Unit]
 Description=Synapse
 
 [Service]
 Type=simple
 WorkingDirectory=%h/synapse
 Environment=LD_PRELOAD=/usr/lib/x86_64-linux-gnu/libjemalloc.so.2
 ExecStart=pipenv run python -m synapse.app.homeserver --config-path=%h/synapse/homeserver.yaml
 
 [Install]
 WantedBy=default.target

Durch Aufruf der folgenden Kommandos wird der Dienst aktiviert und gestartet:

 systemctl --user daemon-reload
 systemctl --user enable synapse.service
 systemctl --user start synapse.service

Einrichten des Apache VHost

Die ~/doms/matrix.beispiel.de/.htaccess mit dem Editor der Wahl öffnen und folgende Konfiguration einfügen:

 DirectoryIndex disabled
 RewriteEngine On
 RewriteBase /
 RewriteCond %{REQUEST_FILENAME} !-f
 RewriteCond %{REQUEST_FILENAME} !-l
 RewriteRule .* http://localhost:32801%{REQUEST_URI} [NE,proxy]
 RequestHeader set X-Forwarded-Proto "https"

Well-Known unter beispiel.de

Damit die User-Accounts das Format @user:beispiel.de haben, der Server aber unter matrix.beispiel.de erreichbar ist, müssen noch folgende zwei Dateien unter der Domain beispiel.de abgelegt werden:

https://beispiel.de/.well-known/matrix/server

 {
   "m.server": "matrix.beispiel.de:443"
 }

https://beispiel.de/.well-known/matrix/client

 {
   "m.homeserver": {
     "base_url": "https://matrix.beispiel.de"
   },
   "m.identity_server": {
     "base_url": "https://vector.im"
   }
 }

Für die muss noch der CORS-Header Access-Control-Allow-Origin "*" gesetzt werden, damit die Datei aus beliebigem Riot-Web im Browser abrufbar ist. Dazu in den Ordner .well-known/matrix/ folgende .htaccess anlegen:

<IfModule mod_headers.c>
  Header set Access-Control-Allow-Origin "*"
</IfModule>

Die Dokumentation dazu findet man unter https://matrix.org/docs/spec/server_server/r0.1.2#get-well-known-matrix-server und https://matrix.org/docs/spec/client_server/r0.5.0#get-well-known-matrix-client

Update von Synapse

mit pipenv:

 systemctl --user stop synapse.service
 cd ~/synapse
 source .venv/bin/activate || pipenv shell
 pipenv install update
 systemctl --user start synapse.service

oder falls Synapse mit pip verwaltet wird:

 systemctl --user stop synapse.service
 cd ~/synapse
 source venv/bin/activate
 pip freeze > requirements.txt
 sed -i "s/==.*//g" requirements.txt
 pip install -r requirements.txt --upgrade
 systemctl --user start synapse.service

Falls Monit verwendet wird statt systemctl:

monit stop synapse
... updaten ...
monit start synapse

Wenn die Föderation für den Synapse Server aktiviert ist, kann mit dem Matrix Federation Tester die eigene Instanz auf die laufende Version geprüft werden. Als Server nicht matrix.example.org eingeben, sondern den öffentlichen Namen, wo auch die Benutzernamen drauf laufen, z.B. example.org

Ansonsten ist die laufende Version auch über die URL https://matrix.example.org/_synapse/admin/v1/server_version zu erfahren.

Element-Web

Element-Web ist aus Server-Seite eine rein statische html+javascript-Kombination, daher:

• Account und Domain anlegen (separat von der Synapse-Domain)
• aktuelles element-web release .tgz herunterladen
• Symlink von htdocs-ssl auf entpacktes element-web-Verzeichnis
• config.sample.json in config.json kopieren und Matrix-Homeserver-Einträge anpassen
• Piwik aus config.json entfernen

SAML mit Synapse

Synapse unterstützt mit Version 1.1.0 SAML. Dazu wie folgt vorgehen:

Das Paket xmlsec1 muss installiert sein:

 $ xmlsec1  --version
 xmlsec1 1.2.23 (openssl)

Das Python-Paket pysaml2 installieren

 cd ~/synapse
 pipenv shell
 pipenv install pysaml2

In der homeserver.yaml die SAML-Direktiven einkommentieren, hier mit dem Beispiel eines SAML IdP unter https://login.beispiel.de/simplesaml/saml2/idp/metadata.php:

 # Once SAML support is enabled, a metadata file will be exposed at
 # https://<server>:<port>/_matrix/saml2/metadata.xml, which you may be able to 
 # use to configure your SAML IdP with. Alternatively, you can manually configure
 # the IdP to use an ACS location of
 # https://<server>:<port>/_matrix/saml2/authn_response.
 #
 saml2_config:
   sp_config:
     # point this to the IdP's metadata. You can use either a local file or
     # (preferably) a URL.
     metadata:
       #local: ["saml2/idp.xml"]
       remote:
         - url: https://login.beispiel.de/simplesaml/saml2/idp/metadata.php

Wichtig ist außerdem, dass die public_baseurl in der homeserver.yaml gesetzt ist, damit Synapse weiß, wie es erreichbar ist und dies in seine SP-Metadaten einbauen kann:

public_baseurl: https://matrix.beispiel.de/

Die Service-Provider-Konfiguration als XML bekommt man von Synapse dann wie schon in der homeserver.yaml als Kommentar beschrieben, unter https://matrix.beispiel.de/_matrix/saml2/metadata.xml

Diese dann in den SAML-IdP-importieren und dann sollte der Single-Sign-On via SAML funktionieren.

Federation Sender Worker für Synapse

Zur Parallelisierung bietet Synapse das Konzept "Worker" an, die spezifische Aufgaben übernehmen, damit der Hauptprozess diese nicht durchführen muss.

Details dazu: https://github.com/matrix-org/synapse/blob/master/docs/workers.md

Ein einfach einzurichtender Worker, der auch viel Last abfedert, ist der Federation Sender Worker, da das Verschicken des Federation-Traffics 10-50% der Serverlast ausmacht.

In der homeserver.yaml die Worker-Konfiguration aktivieren:

 ## Worker ##
 worker_app: synapse.app.homeserver
 daemonize: true

und dazugehörige Listener (Abschnitt listener:) aktivieren:

 # The TCP replication port
 - port: 32892
   bind_address: '127.0.0.1'
   type: replication
 # The HTTP replication port
 - port: 32893
   bind_address: '127.0.0.1'
   type: http
   resources:
    - names: [replication]

Funktionen, die Worker machen sollen, in der homeserver.yaml deaktivieren:

 # disable federation sending here, use worker for it
 send_federation: False

Dann Verzeichnis synapse/workers anlegen, darin federation_sender.yaml:

 worker_app: synapse.app.federation_sender
 
 # The replication listener on the synapse to talk to.
 worker_replication_host: 127.0.0.1
 worker_replication_port: 32892
 worker_replication_http_port: 32893
 
 worker_daemonize: True
 worker_pid_file: /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
 worker_log_config: /home/pacs/xyz00/users/matrix/synapse/federation_sender.log.config

.monitrc um worker erweitern:

 check process federation_sender with pidfile /home/pacs/xyz00/users/matrix/synapse/federation_sender.pid
    start program "/bin/bash -c 'export VIRTUAL_ENV=$HOME/synapse/env && export PATH=$VIRTUAL_ENV/bin:$PATH && cd $HOME/synapse && synctl -w workers/federation_sender.yaml start'"
    stop program "/bin/bash -c '/bin/kill $( cat $HOME/synapse/federation_sender.pid )'"

Monit neu laden und synapse und federation_sender neustarten:

monit reload
monit restart all

Nach Updates ebenfalls immer Hauptprozess und alle Worker neustarten

monit restart all

Sliding Sync Proxy

Zum Zeitpunkt dieser Anleitung werden aktiv neue Element Anwendungen (Element X) und ein neues Syncverfahren entwickelt um Matrix performater und weniger ressourcenhungrig zu machen. Unterstützung hierfür findet sich noch(!) nicht nativ in Synapse, sondern wird mit einem dedizierten kleinen Proxy umgesetzt. Bei stärkerer Matrix Nutzung können die neuen Anwendungen besonders mobil schon eine große Entlastung sein – es sind allerdings noch nicht alle Matrix-Funktionen fertig eingebaut.

Installation

Best practice ist auch hier wieder ein eigener User, sowie eigene Domain.

Wir brauchen:

• eine PostgreSQL Datenbank
• einen freien internen http Port
• eine aktuelle sliding-sync Binary – diese kann hier bezogen werden

Verzeichnisstruktur
Es wird die folgende Struktur vorgeschlagen:

 mkdir -p .config/systemd/user config bin scripts

Binary laden:
Mit den folgenden Befehlen kann die aktuelle Release erkannt, und von dieser das Binary heruntergeladen werden:

export release=`curl -L https://api.github.com/repos/matrix-org/sliding-sync/releases/latest -s | jq -r '.tag_name'`
wget --show-progress -q -O $HOME/bin/syncv3 https://github.com/matrix-org/sliding-sync/releases/download/$release/syncv3_linux_amd64

Nun sollte sich die Datei als ./bin/syncv3 wiederfinden.

Konfiguration

Wir legen eine Environment-Datei an. In diesem Beispiel: config/config.env. Dies sind die wichtigsten Einstellungen – bitte vor ausprobieren anpassen:

SYNCV3_SECRET=$(cat $HOME/.secret)
SYNCV3_SERVER=https://matrix.meinedomain.de
SYNCV3_DB="user=xyz00_syncv3 dbname=xyz00_syncv3 sslmode=disable host=localhost password=sicherespasswort"
SYNCV3_BINDADDR=0.0.0.0:32804
SYNCV3_LOG_LEVEL=warn
# Prometheus
# SYNCV3_PROM=0.0.0.0:8882

Jetzt fehlt noch das Secret, das wir oben aus einer Datei lesen lassen wollen. Das Secret darf nicht gelöscht werden. Andernfalls muss die Datenbank zurückgesetzt werden.

echo -n "$(openssl rand -hex 32)" > $HOME/.secret

.htaccess anpassen

Ähnlich wie für Synapse oben, scheint das Folgende direkt zu funktionieren:

DirectoryIndex disabled
RewriteEngine On
RewriteBase /
RewriteCond %{REQUEST_FILENAME} !-f
RewriteCond %{REQUEST_FILENAME} !-l
RewriteRule .* http://localhost:32804%{REQUEST_URI} [NE,proxy]
RequestHeader set X-Forwarded-Proto "https"

Starten

In der Datei ~/.config/systemd/user/syncv3.service schreiben wir den folgenden Inhalt:

[Unit]
Description=Matrix SyncV3 Proxy
After=postgresql.service

[Service]
Type=simple
WorkingDirectory=%h
EnvironmentFile=%h/config/config.env
ExecStart=%h/bin/syncv3

[Install]
WantedBy=default.target

Sicherheitshalber jetzt noch einmal export XDG_RUNTIME_DIR=/run/user/$UID damit wir systemd auch steuern können und dann: systemctl enable --user --now syncv3. Logs können beispielsweise mittels journalctl --user -xefu syncv3 betrachtet werden.

Auffindbar machen

Moderne Anwendungen wie Element X erwarten automatisch zu erkennen, ob syncv3 Support vorhanden ist. Hierfür müssen wir die well-known für die Hauptdomain des Matrixservers ergänzen. Also den server_name des Synapse servers.

Konkret muss /.well-known/matrix/client auf das Folgende erweitert werden:

"org.matrix.msc3575.proxy": {
    "url": "https://syncv3.meinedomain.de"
}

Links

• https://matrix.org/docs/projects/server/synapse
• https://github.com/element-hq/synapse
• https://github.com/element-hq/synapse/blob/master/INSTALL.md
• https://github.com/matrix-org/sliding-sync
• https://matrix.org/docs/spec/
• https://www.hostsharing.net/loesungen/matrix/
• https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/synapse
• https://codeberg.org/tpokorra/hs.ansible/src/branch/main/playbooks/element