So richten Sie einen Matrix-Server auf einem Raspberry Pi 4 mit Conduit ein

Ein Raspberry Pi 4 eignet sich hervorragend als kleiner Matrix-Homeserver für Privathaushalte, Gruppen oder Labore, und Conduit wurde speziell für den Einsatz mit leichter Hardware entwickelt. Matrix ist ein offenes Protokoll für dezentrale Kommunikation: Ihre Benutzer verbinden sich mit einem Homeserver , der ihre Konten und Raumdaten speichert. Die Föderation ermöglicht es diesem Homeserver, Ereignisse mit anderen Matrix-Servern auszutauschen.

Diese Anleitung verwendet Conduit in Docker mit NGINX als vorgeschaltetem HTTPS-Server. Dadurch bleibt der Matrix-Dienst auf dem Raspberry Pi isoliert, während nur die öffentlichen Webports freigegeben werden. Die Anweisungen wurden anhand der Dokumentation zu Conduit, Matrix, Raspberry Pi, Docker und NGINX (Stand: Oktober 2026) überprüft. Eine wichtige Einschränkung vorab: Conduit befindet sich noch im Beta-Stadium und ist daher am besten für Nutzer geeignet, die akzeptieren, dass einige Matrix-Funktionen und ältere Raumversionen möglicherweise nicht exakt so funktionieren wie in einer ausgereiften Synapse-Umgebung. Prüfen Sie die offizielle Conduit-Projektseite, bevor Sie Conduit für einen kritischen Dienst einsetzen.

1. Machen Sie sich mit der Einrichtung vertraut, bevor Sie irgendetwas installieren.

Der fertige Ablauf ist einfach: Ein Matrix-Client wie Element verbindet sich mit dem Server https://matrix.example.com; NGINX beendet die TLS-Verbindung und leitet die Anfrage an Conduit auf dem Raspberry Pi weiter; Conduit speichert seine Datenbank in einem persistenten Docker-Speicher. Wenn die Föderation aktiviert ist, erreichen andere Homeserver denselben öffentlichen HTTPS-Endpunkt.

Sie benötigen einen Raspberry Pi 4, ein zuverlässiges Netzteil, eine microSD-Karte oder SSD sowie ein 64-Bit-Betriebssystem. Für einen Server, den Sie längerfristig nutzen möchten, ist eine SSD empfehlenswert, da Matrix kontinuierlich Datenbank- und Mediendaten speichert. Sie benötigen außerdem einen Domainnamen, falls der Server über das öffentliche Internet erreichbar sein soll.

Die aktuelle 64-Bit-Version von Raspberry Pi OS basiert seit dem 15. September 2026 auf Debian 13 „Trixie“. Raspberry Pi OS Lite ist für den Pi 4 verfügbar. Siehe die offizielle Downloadseite von Raspberry Pi OS . Für diesen Server ist Lite gut geeignet, da es auf eine unnötige Desktop-Umgebung verzichtet.

Wählen Sie den Matrix-Servernamen sorgfältig aus.

In dieser Anleitung lautet der Servername matrix.example.com. Eine resultierende Matrix-Benutzer-ID sieht folgendermaßen aus @alice:matrix.example.com: . Behandeln Sie diesen Namen als langfristige Identitätswahl. Matrix-IDs und Verbundreferenzen enthalten den Servernamen, daher ist eine spätere Änderung nicht gleichbedeutend mit der einfachen Umbenennung eines Webhosts.

2. Installieren Sie Raspberry Pi OS und aktualisieren Sie den Pi.

Schreiben Sie Raspberry Pi OS Lite (64-Bit) mit dem Raspberry Pi Imager auf die Speicherkarte oder SSD. Aktivieren Sie SSH während des Imaging-Vorgangs, wenn Sie eine Installation ohne Bildschirm wünschen, und starten Sie den Pi. Vergewissern Sie sich, dass Sie ein 64-Bit-ARM-System verwenden.

uname -m
cat /etc/os-release

uname -mNormalerweise sollte eine Meldung erscheinen aarch64. Installieren Sie anschließend die aktuellen Updates:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

3. Docker Engine und Compose installieren

Die Docker-Dokumentation empfiehlt, dass Benutzer von Raspberry Pi OS 64-Bit die unterstützten Debian ARM64-Pakete anstelle des älteren 32-Bit-Pfads von Raspberry Pi OS verwenden sollten. Die offizielle Vorgehensweise ist auf der Docker Engine-Seite für Debian beschrieben . Die folgende Repository-Konfiguration folgt diesem Ansatz:

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg   -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io   docker-buildx-plugin docker-compose-plugin

sudo docker run --rm hello-world

Wenn der letzte Befehl die Docker-Bestätigung „hello-world“ ausgibt, funktioniert die Container-Laufzeitumgebung. Sie können sudo dockerdie Anleitung wie gewohnt fortsetzen. Das Hinzufügen Ihres Kontos zur dockerGruppe ist optional, aber beachten Sie, dass die Docker-Gruppenmitgliedschaft Ihnen faktisch die volle Kontrolle über den Host gewährt.

4. Erstellen einer Leitungskonfiguration

Conduit kann über eine TOML-Datei oder Umgebungsvariablen konfiguriert werden. Die offizielle Conduit-Konfigurationsreferenz listet die Felder server_name, database_backendund database_pathals Pflichtfelder auf und empfiehlt RocksDB.

Erstellen Sie ein Arbeitsverzeichnis:

sudo mkdir -p /opt/conduit
sudo chown "$USER":"$USER" /opt/conduit
cd /opt/conduit
nano conduit.toml

Verwenden Sie diese Ausgangskonfiguration und ersetzen Sie den Hostnamen und das Registrierungstoken:

[global]
server_name = "matrix.example.com"
database_backend = "rocksdb"
database_path = "/var/lib/matrix-conduit/"
address = "0.0.0.0"
port = 6167

allow_registration = true
registration_token = "replace-with-a-long-random-secret"
allow_federation = true
trusted_servers = ["matrix.org"]

Warum gerade 0.0.0.0hier? Innerhalb eines Containers muss Conduit auf der Container-Schnittstelle lauschen, damit Docker darauf zugreifen kann. Der Host-seitige Port ist weiterhin nur an den Host gebunden 127.0.0.1, daher ist Port 6167 nicht direkt im Internet erreichbar.

5. Conduit mit Docker Compose ausführen

Erstellen /opt/conduit/docker-compose.yml:

services:
  conduit:
    image: registry.gitlab.com/famedly/conduit/matrix-conduit:latest
    container_name: matrix-conduit
    restart: unless-stopped
    ports:
      - "127.0.0.1:6167:6167"
    volumes:
      - ./conduit.toml:/etc/conduit.toml:ro
      - conduit-data:/var/lib/matrix-conduit/
    environment:
      CONDUIT_CONFIG: /etc/conduit.toml

volumes:
  conduit-data:

Das stabile GitLab-Registry-Image ist das in der offiziellen Conduit-Docker-Dokumentation empfohlene Image . Vermeiden Sie es, ein altes Image-Tag aus einem beliebigen Tutorial zu kopieren; verwenden Sie stattdessen die offizielle Registry und lesen Sie die Versionshinweise vor Aktualisierungen.

Starten Sie den Dienst und überprüfen Sie ihn:

cd /opt/conduit
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=100 conduit

Sie möchten, dass der Container im Status „Aktiv“ oder „Ausgeführt“ verbleibt, Upohne wiederholte Neustartschleifen. Überprüfen Sie vor der Konfiguration von NGINX die lokale API:

curl http://127.0.0.1:6167/_matrix/client/versions

6. DNS auf den Pi umleiten und NGINX vor Conduit schalten.

Erstellen Sie einen AEintrag, der matrix.example.comauf Ihre öffentliche IPv4-Adresse verweist. Wenn Sie einen AAAAsolchen Eintrag veröffentlichen, stellen Sie sicher, dass IPv6 den Raspberry Pi auch tatsächlich erreicht; ein fehlerhafter IPv6-Eintrag kann dazu führen, dass Clients nicht funktionieren, selbst wenn IPv4 funktioniert.

Bei einem typischen Heimrouter leiten Sie die TCP-Ports 80 und 443 an den Raspberry Pi weiter. Falls Ihr Internetanbieter Carrier-Grade NAT (CGNAT) verwendet, funktioniert die normale eingehende Portweiterleitung möglicherweise nicht. In diesem Fall benötigen Sie eine öffentliche IP-Adresse, einen VPS/Reverse-Tunnel oder eine andere Hosting-Lösung.

NGINX installieren:

sudo apt install -y nginx

Erstellen /etc/nginx/sites-available/matrix:

server {
    listen 80;
    server_name matrix.example.com;

    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:6167;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Die offiziellen Reverse-Proxy- Dokumente von NGINX proxy_passund die hier verwendeten weitergeleiteten Header sind ebenfalls aufgeführt.

sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/matrix
sudo nginx -t
sudo systemctl reload nginx

7. HTTPS und Matrixerkennung aktivieren

Matrix benötigt für den normalen öffentlichen Einsatz eine gültige HTTPS-Verbindung. Ein Zertifikat sollte erst dann beantragt werden, wenn die DNS-Auflösung zum Raspberry Pi erfolgreich war und Port 80 erreichbar ist. Debian Trixie stellt Certbot-Pakete bereit; das Certbot-Projekt veröffentlicht außerdem aktuelle plattformspezifische Anleitungen unter certbot.eff.org .

Ein gängiger Debian/NGINX-Weg ist:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d matrix.example.com

Nachdem Certbot den virtuellen NGINX-Host aktualisiert hat, testen Sie die Konfiguration erneut:

sudo nginx -t
sudo systemctl reload nginx

Da in dieser Anleitung derselbe Hostname für den Matrix-Servernamen und den öffentlichen Endpunkt verwendet wird, kann Conduit die Matrix- /.well-knownErkennungspfade über den Reverse-Proxy beantworten. Die Matrix-Spezifikation definiert diese Endpunkte, damit Clients und andere Server die korrekte Homeserver-URL ermitteln können. Siehe die Matrix-Client-Server-Spezifikation .

8. Erstellen Sie das erste Konto und überprüfen Sie anschließend den Server.

Laut der Docker-Dokumentation von Conduit wird das erste auf einem neuen Homeserver erstellte Konto zum Administrator. Öffnen Sie einen Matrix-Client, der Registrierungstoken unterstützt, wählen Sie einen benutzerdefinierten Homeserver aus und geben Sie Folgendes ein:

https://matrix.example.com

Registrieren Sie das erste Konto mit dem Token von [Link einfügen] conduit.toml. Führen Sie dies kurz nach der Inbetriebnahme des Dienstes durch. Wenn Sie keine weiteren Registrierungen wünschen, bearbeiten Sie die Konfiguration entsprechend allow_registration = falseund starten Sie den Container neu.

cd /opt/conduit
sudo docker compose restart conduit

Führen Sie nun von jedem Rechner, der die Domäne erreichen kann, drei Prüfungen durch:

curl https://matrix.example.com/_matrix/client/versions

curl https://matrix.example.com/.well-known/matrix/client

curl https://matrix.example.com/.well-known/matrix/server

Die erste Anfrage sollte JSON mit einer Beschreibung der unterstützten Matrix-Client-API-Versionen zurückgeben. Die bekannten Anfragen sollten gültige JSON-Informationen zur Erkennung zurückgeben. Verwenden Sie für die Föderation außerdem den Matrix Federation Tester und versuchen Sie, mit dem neuen Konto einem föderierten Raum beizutreten.

Häufige Fehler, die die Funktion eines Raspberry Pi Matrix-Servers verhindern

• Die Verwendung eines 32-Bit-Betriebssystems ist unnötig: Für einen Pi 4 sollte man Raspberry Pi OS 64-Bit und die von Docker unterstützten Debian ARM64-Pakete verwenden.
• Conduit direkt zugänglich machen: Port 6167 auf dem Host gebunden lassen 127.0.0.1und HTTPS über NGINX bereitstellen.
• Registrierung ungeschützt offen lassen: Verwenden Sie bei der Ersteinrichtung ein starkes Registrierungstoken und deaktivieren Sie die Registrierung anschließend, wenn Sie sie nicht mehr benötigen.
• Falsche DNS-Veröffentlichung: Sowohl IPv4- als auch IPv6-Einträge müssen zu einem funktionierenden Endpunkt führen, wenn Sie beide veröffentlichen.
• Vergessene Router- oder Firewall-Regeln: Ein korrekter Container kann den blockierten eingehenden TCP-Verkehr über die Ports 80/443 nicht kompensieren.
• Unter der Annahme, dass Messaging und Sprachanrufe identisch sind: Matrix-Messaging funktioniert auch bei ausgefallenen Anrufen. Laut Conduits Dokumentation benötigt die Sprachkommunikation einen TURN-Server wie Coturn.
• Backups überspringen: Die FAQ von Conduit empfiehlt, Conduit zu stoppen, bevor eine normale Dateisystemkopie der Datenbank erstellt wird, es sei denn, Sie verwenden einen geeigneten Dateisystem-Snapshot. Sichern Sie das Docker-Volume und Ihre Konfiguration vor Upgrades.

So sieht eine erfolgreiche Installation aus

Sie sind fertig, wenn alle folgenden Bedingungen erfüllt sind: Der Conduit-Container bleibt nach einem Neustart aktiv; https://matrix.example.com/_matrix/client/versionser gibt JSON zurück; ein Matrix-Client kann sich bei Ihrem benutzerdefinierten Homeserver registrieren oder anmelden; das Konto kann einen Raum erstellen und eine Nachricht senden; und, falls die Föderation aktiviert ist, kann der Föderationstester den Server erreichen und der Benutzer kann mit Konten auf einem anderen Homeserver kommunizieren.

Für eine kleine Raspberry-Pi-Installation stellt dies eine saubere Basiskonfiguration dar, nicht das Ende der Administration. Überwachen Sie den freien Speicherplatz, halten Sie Raspberry Pi OS und Docker auf dem neuesten Stand, sichern Sie die Datenbank und lesen Sie die offizielle Conduit-Dokumentation , bevor Sie zusätzliche Funktionen aktivieren. Conduit ist nach wie vor eine schlanke und attraktive Option für Hardware der Pi-Klasse, der Beta-Status sollte jedoch unbedingt berücksichtigt werden.