Matrix Synapse mit Docker Compose und PostgreSQL bereitstellen

Führen Sie Synapse als Docker-Compose-Projekt mit einem persistenten Konfigurationsverzeichnis und einer PostgreSQL-Datenbank aus. Die folgende Konfiguration generiert die Signaturschlüssel von Synapse homeserver.yaml, stellt die Verbindung zu PostgreSQL her und hält den HTTP-Listener auf localhost, sodass Sie HTTPS und Federation hinter einem Reverse-Proxy platzieren können, bevor Sie den Server für das Internet öffnen.

Synapse ist der Matrix-Homeserver: Er speichert Accounts, Räume, Ereignisse und Medien für einen Server. Docker Compose startet die Synapse- und PostgreSQL-Container mithilfe einer einzigen YAML-Datei. Dies ist ein Ausgangspunkt für einen einzelnen Rechner, keine vollständige öffentliche Matrix-Bereitstellung.

Bevor Sie beginnen

Installieren Sie Docker Engine und das Docker Compose-Plugin und überprüfen Sie anschließend die docker compose versionFunktion. Docker Desktop enthält Compose unter Windows und macOS; Linux-Benutzer können das Compose-Plugin aus dem Docker-Paket-Repository installieren. Siehe die Installationsanleitung für Docker Compose .

Wählen Sie den permanenten Matrix-Servernamen, bevor Sie die Konfiguration generieren. Dieser Name erscheint in Benutzerkennungen wie z. B. „matrixservername“ @alex:matrix.example.org, und eine spätere Änderung ist keine einfache Hostnamenänderung. In diesem Beispiel matrix.example.orgist „matrixservername“ sowohl der Matrix-Servername als auch der öffentliche Hostname. Richten Sie für einen öffentlichen Server dessen DNS-Eintrag auf Ihren Host ein und planen Sie einen HTTPS-Reverse-Proxy. Der von Synapse generierte HTTP-Listener auf Port 8008 eignet sich für lokale Tests; laut Installationsdokumentation ist für den praktischen Einsatz HTTPS erforderlich.

1. Erstelle ein Projekt und ein Geheimnis.

Erstellen Sie auf dem Docker-Host ein Arbeitsverzeichnis und die persistenten Ordner. Der synapseOrdner enthält die generierte Konfiguration und den Signaturschlüssel; data/postgresder Ordner enthält die Datenbankdateien.

mkdir -p ~/matrix-synapse/synapse ~/matrix-synapse/data/postgres
cd ~/matrix-synapse
umask 077
openssl rand -hex 32

Kopieren Sie die Ausgabe des Befehls in eine neue .envDatei DB_PASSWORD=.... Bewahren Sie diese Datei vertraulich auf und erstellen Sie eine Sicherungskopie. Compose liest .envdie Compose-Datei auf Ersetzungen; Synapse erweitert diese Variablen nicht automatisch homeserver.yaml. Sie werden in Schritt 3 dasselbe Passwort in dieser Konfiguration eingeben.

Beispielhafte Terminalansicht eines Matrix-Synapse-Projektverzeichnisses mit docker-compose.yml, einer Umgebungsdatei, einem Synapse-Konfigurationsordner und einem Datenordner.
Ein Projektordner trennt die Compose-Definition, die Synapse-Konfiguration und die persistenten Datenbankdateien.

2. Definieren Sie die beiden Dienste.

Erstellen Sie docker-compose.ymldie Datei im Projektverzeichnis. Dieses Beispiel verwendet das offizielle Synapse-Image von Element HQ und PostgreSQL 16. Der Synapse-Port ist an den Loopback-Port gebunden, nicht an jede Netzwerkschnittstelle. Der Health-Check sorgt dafür, dass Compose auf PostgreSQL wartet, bevor Synapse gestartet wird.

services:
  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    environment:
      SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
    volumes:
      - ./synapse:/data
    ports:
      - "127.0.0.1:8008:8008"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: --encoding=UTF-8 --lc-collate=C --lc-ctype=C
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
      interval: 10s
      timeout: 5s
      retries: 5

Fügen Sie den Wert mit dem Zufallswert aus Schritt 1 DB_PASSWORD=your-generated-valueein .env. Speichern Sie diese Datei nicht in der Versionsverwaltung. Wenn Sie die Hauptversion von PostgreSQL später ändern, befolgen Sie die Aktualisierungsprozedur von PostgreSQL, anstatt einfach ein neueres Image auf ein bestehendes Datenverzeichnis zu verweisen.

3. Synapse-Konfiguration generieren und PostgreSQL auswählen

Generieren Sie die Erstkonfiguration und den Signaturschlüssel im eingebundenen synapseVerzeichnis. Verwenden Sie denselben Servernamen, den Sie oben gewählt haben. Legen Sie die Statistikoption explizit fest; hier ist sie no.

docker compose run --rm --no-deps \
  -e SYNAPSE_SERVER_NAME=matrix.example.org \
  -e SYNAPSE_REPORT_STATS=no \
  synapse generate

Der offizielle Container- generateModus erstellt homeserver.yamlden erforderlichen Signaturschlüssel. Öffnen Sie synapse/homeserver.yamlden Abschnitt zur SQLite-Datenbank und ersetzen Sie ihn durch den folgenden Inhalt. Ersetzen Sie ` <sqlite-database> PASTE_THE_SAME_DB_PASSWORD_HERE` durch den exakten Wert, der in `<sqlite-database>` gespeichert ist .env. Dieses Feld ist ein direkter Synapse-Konfigurationswert und keine Compose-Interpolation.

database:
  name: psycopg2
  args:
    user: synapse
    password: PASTE_THE_SAME_DB_PASSWORD_HERE
    dbname: synapse
    host: db
    port: 5432
    cp_min: 5
    cp_max: 10
Beispielhafte Ansicht des homeserver.yaml-Editors mit PostgreSQL, konfiguriert über psycopg2, Datenbank Synapse, Host db, Port 5432 und einem Verbindungspool.
Der Abschnitt „Synapse database“ verweist auf den Compose-Dienstnamen „db“ auf dem internen Port von PostgreSQL.

Die generierte Datei sollte registration_shared_secretvertraulich behandelt werden. Synapse verwendet sie für das Kommandozeilen-Tool zur Benutzerregistrierung; jeder, der Zugriff darauf hat, kann Konten erstellen, auch Administratoren. Deaktivieren Sie die öffentliche Registrierung, es sei denn, Sie beabsichtigen, diese anzubieten und haben die zugehörigen Missbrauchskontrollmaßnahmen geprüft.

4. Starten Sie Synapse und überprüfen Sie die Protokolle.

Überprüfen Sie im Verzeichnis, das die Datei enthält docker-compose.yml, die Compose-Datei und starten Sie die Dienste:

docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=100 synapse db

Der erste Befehl prüft, ob Compose die Datei parsen und auflösen kann DB_PASSWORD. Der nächste Befehl startet die Datenbank und den Homeserver im Hintergrund. Überprüfen Sie die Protokolle auf Datenbankverbindungsfehler oder eine fehlende Konfigurationsdatei. Da diese Einrichtung die lokalen Ordner einbindet, bleiben die Datenbank- und Synapse-Konfiguration auch nach dem Neuerstellen von Containern erhalten.

Beispielhafte Terminal-Eingabeaufforderung mit dem Befehl docker compose up -d zum Starten des Synapse-Stacks.
Starten Sie die Synapse- und PostgreSQL-Dienste, nachdem Sie die Konfiguration generiert und überprüft haben.

5. Lokalen Endpunkt überprüfen und ein Konto erstellen.

Führen Sie die Anfrage für die Matrix-Clientversionen vom Docker-Host aus. Eine JSON-Antwort bedeutet, dass die Client-API antwortet; eine leere Antwort, eine Verbindungsablehnung oder ein HTTP-Fehler bedeutet, dass Sie die Synapse-Protokolle überprüfen und sicherstellen sollten, dass Port 8008 aktiv ist.

curl -fsS http://127.0.0.1:8008/_matrix/client/versions

Sobald die Seite antwortet, erstellen Sie interaktiv einen ersten Benutzer. Dieser Befehl fordert Sie zur Eingabe eines Benutzernamens und eines Passworts auf; wählen Sie „Nein“ für Administrator, es sei denn, Sie benötigen ausdrücklich ein Administratorkonto.

docker compose exec synapse register_new_matrix_user \
  -c /data/homeserver.yaml http://localhost:8008
Beispielhafte Terminal-Eingabeaufforderung mit einer curl-Anfrage an den Synapse Matrix-Clientversions-Endpunkt auf localhost Port 8008.
Eine erfolgreiche Antwort des Versionsendpunkts bestätigt, dass Synapse lokal antwortet; diese Beispielaufforderung zeigt die Überprüfung, nicht das Testergebnis.

Sorgen Sie dafür, dass es sicher erreichbar ist.

Die Portweiterleitung auf localhost ist beabsichtigt: Sie verhindert den direkten öffentlichen Zugriff auf den unverschlüsselten HTTP-Listener. Konfigurieren Sie für Remote-Clients einen Reverse-Proxy mit einem gültigen TLS-Zertifikat und leiten Sie Matrix-Pfade an Synapse weiter. Der Proxy muss die Header `<name> X-Forwarded-For` und ` <head>` weiterleiten X-Forwarded-Proto; aktivieren Sie in der generierten Listener-Konfiguration die Weiterleitung x_forwarded: truefür Port 8008. Binden Sie einen containerisierten Synapse-Listener nicht ausschließlich an `<name>` 127.0.0.1, da dies verhindert, dass ein Proxy-Container ihn erreicht. Wenn der Reverse-Proxy ebenfalls containerisiert ist, platzieren Sie ihn und Synapse in einem gemeinsamen Docker-Netzwerk und leiten Sie die Anfragen an den Dienstnamen `<servicename>` weiter synapse:8008.

Die Föderation ist vom lokalen Startvorgang unabhängig. Andere Matrix-Server müssen Ihren Server finden und erreichen können, üblicherweise über Port 8448 oder per delegierter HTTPS-Erkennung. DNS, Reverse-Proxy-Routing und alle erforderlichen .well-knownEinträge müssen mit dem gewählten Servernamen übereinstimmen. Befolgen Sie die Dokumentation und Installationsanleitung von Synapse zum Reverse-Proxy, bevor Sie einen öffentlichen Heimserver einrichten. Für zuverlässige Medienverbindungen wird außerdem ein TURN-Server benötigt.

Wenn Synapse keine Verbindung zu PostgreSQL herstellen kann, überprüfen Sie, ob der Compose-Dienstname korrekt hostist , ob beide Passwörter exakt übereinstimmen und ob der Datenbankcontainer fehlerfrei läuft. Ist der Endpunkt nicht erreichbar, prüfen Sie die Synapse-Protokolle und ob ein anderer Dienst bereits Port 8008 verwendet. Sichern Sie sowohl das PostgreSQL-Datenverzeichnis als auch die Synapse-Konfiguration und den Signaturschlüssel; der Signaturschlüssel ist für die Identität des Servers unerlässlich.dbdocker compose ps

Detaillierte Informationen zur PostgreSQL-Konfiguration finden Sie im PostgreSQL-Leitfaden von Synapse . Informationen zu Containeroptionen und Benutzererstellung finden Sie in der offiziellen Synapse-Docker-Dokumentation .

Einen Kommentar hinterlassen

Richten Sie einen benutzerdefinierten Matrix-Raumalias auf Ihrer eigenen Domain ein.

Weisen Sie einem Matrix-Raum mithilfe von Element oder der Matrix-API eine einfach zu teilende Adresse in Ihrer Domäne zu, inklusive Prüfungen auf Berechtigungen, Synapse-Namensgebung und Föderation.

Richten Sie coturn für zuverlässige Matrix-Sprach- und Videoanrufe ein.

Konfigurieren Sie coturn und Synapse mit übereinstimmenden TURN-Zugangsdaten, öffnen Sie die erforderlichen Relay-Ports und überprüfen Sie, ob Matrix-Clients Relay-Kandidaten erhalten können.

Matrix Synapse mit Docker Compose und PostgreSQL bereitstellen

Matrix Synapse mit Docker Compose und PostgreSQL bereitstellen

Richten Sie einen persistenten Synapse-Homeserver mit Docker Compose, PostgreSQL, einer privaten Konfiguration und Prüfungen ein, bevor Sie ihn über HTTPS zugänglich machen.

Design und Branding von Element Web anpassen

Legen Sie einen Markennamen, benutzerdefinierte Farben und Anmeldeinformationen für Ihre Element Web-Bereitstellung fest und behalten Sie dabei im Blick, welche Teile weiterhin unter der Marke Element vertrieben werden.

Synapses Systemd-Dateilimit ohne Rätselraten erhöhen

Synapses Systemd-Dateilimit ohne Rätselraten erhöhen

Prüfen Sie, ob Synapse die maximale Anzahl offener Dateien pro Prozess erreicht hat, richten Sie ein systemd-Drop-in für den richtigen Dienst oder Worker ein und überprüfen Sie das aktuelle Limit.

Element zeigt „Entschlüsselung fehlgeschlagen“ an? Stellen Sie den fehlenden Raumschlüssel wieder her.

Element zeigt „Entschlüsselung fehlgeschlagen“ an? Stellen Sie den fehlenden Raumschlüssel wieder her.

Finden Sie heraus, ob der Fehler auf einen bestimmten Browser oder ein bestimmtes Ereignis beschränkt ist, und verwenden Sie dann den Wiederherstellungsschlüssel von Element oder ein vertrauenswürdiges Gerät, ohne Ihre übrigen verschlüsselten Verlaufsdaten zu riskieren.

Alte Synapse-Nachrichten und Mediendateien bereinigen, ohne Daten zu verlieren

Verwenden Sie die Verlaufs- und Medienbereinigungs-APIs oder die Aufbewahrungseinstellungen von Synapse, um veraltete Daten sicher zu entfernen, und überprüfen Sie anschließend den Abschluss und die Wiederherstellung des Speicherplatzes.

Erstelle einen Matrix-Echo-Bot in Python mit Simple-Matrix-Bot-Lib

Erstelle einen Matrix-Echo-Bot in Python mit Simple-Matrix-Bot-Lib

Installieren Sie die aktuelle Bibliothek, verbinden Sie ein dediziertes Matrix-Konto und führen Sie einen kleinen !echo-Bot mit sichererer Anmeldeinformationsverwaltung und einem klaren Test aus.

Verbinde Matrix mit WhatsApp, Telegram und Discord über separate Brücken.

Verbinde Matrix mit WhatsApp, Telegram und Discord über separate Brücken.

Richten Sie drei Mauttrix-Bridges mit separaten Registrierungen, Logins und Tests ein – und vermeiden Sie Überraschungen bei Docker-Netzwerken, Kontorichtlinien und Synchronisierung.

Synapse Media-Speicherplatz freigeben, ohne freigegebene Dateien zu beschädigen

Ermitteln Sie, was den Synapse-Speicher belegt, legen Sie eine sichere Medienaufbewahrung fest und leeren Sie den Remote-Cache, ohne Dateien direkt von der Festplatte zu löschen.