Comment configurer un serveur Matrix sur Raspberry Pi 4 avec Conduit

Un Raspberry Pi 4 peut constituer un serveur Matrix domestique compact et pratique pour un foyer, un groupe privé ou un laboratoire, et Conduit est conçu pour fonctionner avec du matériel léger. Matrix est un protocole ouvert de communication décentralisée : vos utilisateurs se connectent à un serveur domestique qui stocke leurs comptes et les données de leurs salles, tandis que la fédération permet à ce serveur d'échanger des événements avec d'autres serveurs Matrix.

Ce guide utilise Conduit dans un conteneur Docker, avec NGINX en amont pour le protocole HTTPS. Cela permet d'isoler le service Matrix sur le Raspberry Pi tout en exposant uniquement les ports web publics. Les instructions ont été vérifiées à l'aide de la documentation de Conduit, Matrix, Raspberry Pi, Docker et NGINX disponible en octobre 2026. Une limitation importante doit être soulignée d'emblée : Conduit est encore en version bêta . Il est donc plutôt destiné aux utilisateurs qui acceptent que certaines fonctionnalités de Matrix et les anciennes versions de salles puissent ne pas fonctionner exactement comme sur un déploiement Synapse stable. Consultez la documentation officielle du projet Conduit avant de l'utiliser pour un service critique.

1. Comprenez la configuration avant d'installer quoi que ce soit.

Le chemin final est simple : un client Matrix tel qu’Element se connectehttps://matrix.example.com ; NGINX termine la connexion TLS et transmet la requête à Conduit sur le Raspberry Pi ; Conduit stocke sa base de données dans un espace de stockage Docker persistant. Si la fédération est activée, les autres serveurs domestiques peuvent accéder au même point de terminaison HTTPS public.

Vous aurez besoin d'un Raspberry Pi 4, d'une alimentation fiable, d'une carte microSD ou d'un SSD, et d'un système d'exploitation 64 bits. Un SSD est préférable pour un serveur destiné à une utilisation prolongée, car Matrix y écrit en continu des données de base de données et des fichiers multimédias. Un nom de domaine sera également nécessaire si le serveur doit être accessible depuis Internet.

Au 15 septembre 2026, la version actuelle de Raspberry Pi OS 64 bits est basée sur Debian 13 « Trixie », et Raspberry Pi OS Lite est disponible pour le Pi 4. Consultez la page de téléchargement officielle de Raspberry Pi OS . Pour ce serveur, la version Lite est parfaitement adaptée car elle évite un environnement de bureau superflu.

Choisissez soigneusement le nom du serveur Matrix.

Dans ce guide, le nom du serveur est matrix.example.com. L'identifiant utilisateur Matrix qui en résulte ressemble à @alice:matrix.example.com. Ce nom est un choix d'identité permanent. Les identifiants Matrix et les références de fédération incluent le nom du serveur ; le modifier ultérieurement ne revient donc pas à renommer un hébergeur web.

2. Installez Raspberry Pi OS et mettez à jour le Pi

Écrivez Raspberry Pi OS Lite 64 bits sur la carte ou le SSD avec Raspberry Pi Imager, activez SSH pendant l'installation si vous souhaitez une installation sans écran, puis démarrez le Raspberry Pi. Vérifiez que vous utilisez un système ARM 64 bits.

uname -m
cat /etc/os-release

uname -mdevrait normalement signaler un problème aarch64. Installez ensuite les mises à jour actuelles :

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

3. Installez Docker Engine et Compose

La documentation de Docker indique que les utilisateurs de Raspberry Pi OS 64 bits doivent utiliser les paquets Debian ARM64 compatibles plutôt que l'ancienne version 32 bits. La procédure officielle est disponible sur la page Docker Engine pour Debian . La configuration de dépôt suivante suit cette approche :

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

Si la dernière commande affiche la confirmation « Hello World » de Docker, l'environnement d'exécution du conteneur fonctionne. Vous pouvez continuer à l'utiliser sudo dockerpour le reste du guide. L'ajout de votre compte au dockergroupe est facultatif, mais n'oubliez pas que l'appartenance à un groupe Docker vous confère un contrôle total sur l'hôte.

4. Créer une configuration de conduit

Conduit peut être configuré à l'aide d'un fichier TOML ou de variables d'environnement. La documentation officielle de configuration de Conduit indique que les champs ` <nom_du_champ>` server_name, database_backend`<nom_du_champ>` et ` database_path<nom_du_champ>` sont obligatoires et recommande RocksDB.

Créez un répertoire de travail :

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

Utilisez cette configuration initiale et remplacez le nom d'hôte et le jeton d'enregistrement :

[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"]

Pourquoi 0.0.0.0ici ? À l’intérieur d’un conteneur, Conduit doit écouter sur l’interface du conteneur pour que Docker puisse y accéder. Le port côté hôte restera limité à l’interface réseau 127.0.0.1, le port 6167 n’est donc pas exposé directement sur Internet.

5. Exécuter Conduit avec Docker Compose

Créer /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:

L'image stable du registre GitLab est celle recommandée par la documentation officielle de Conduit Docker . Évitez de copier une ancienne étiquette d'image provenant d'un tutoriel quelconque ; utilisez le registre officiel et consultez les notes de version avant toute mise à jour.

Démarrez le service et inspectez-le :

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

Vous souhaitez que le conteneur reste en Upétat d'exécution sans redémarrages intempestifs. Avant de configurer NGINX, vérifiez l'API locale :

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

6. Configurez le DNS pour qu'il pointe vers le Raspberry Pi et placez NGINX devant Conduit.

Créez un Aenregistrement IPv6 matrix.example.compointant vers votre adresse IPv4 publique. Si vous publiez cet AAAAenregistrement, assurez-vous que l'IPv6 atteint bien le Raspberry Pi ; un enregistrement IPv6 incorrect peut empêcher les clients de fonctionner, même si l'IPv4 est opérationnel.

Sur un routeur domestique classique, redirigez les ports TCP 80 et 443 vers le Raspberry Pi. Si votre fournisseur d'accès utilise un NAT de niveau opérateur (CGNAT), la redirection de ports entrants standard peut ne pas fonctionner ; dans ce cas, vous aurez besoin d'une adresse IP publique, d'un VPS/tunnel inversé ou d'une autre solution d'hébergement.

Installer NGINX :

sudo apt install -y nginx

Créer /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;
    }
}

Documents du guide officiel de proxy inverse de NGINX proxy_passet en-têtes transférés utilisés ici.

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

7. Activer HTTPS et la découverte de la matrice

Pour un déploiement public normal, Matrix requiert un certificat HTTPS valide. Obtenez-le uniquement une fois que le DNS pointe vers le Raspberry Pi et que le port 80 est accessible. Debian Trixie fournit des paquets Certbot, et le projet Certbot publie également des instructions spécifiques à chaque plateforme sur certbot.eff.org .

Une méthode courante sous Debian/NGINX consiste à :

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

Après la mise à jour de l'hôte virtuel NGINX par Certbot, testez à nouveau la configuration :

sudo nginx -t
sudo systemctl reload nginx

Ce guide utilisant le même nom d'hôte pour le serveur Matrix et le point de terminaison public, Conduit peut répondre aux /.well-knownrequêtes de découverte Matrix via le proxy inverse. La spécification Matrix définit ces points de terminaison afin que les clients et autres serveurs puissent trouver l'URL correcte du serveur d'accueil. Voir la spécification client-serveur Matrix .

8. Créez le premier compte, puis vérifiez le serveur.

La documentation Docker de Conduit indique que le premier compte créé sur un nouveau serveur d'accueil devient l'administrateur. Ouvrez un client Matrix compatible avec les jetons d'enregistrement, sélectionnez un serveur d'accueil personnalisé et saisissez :

https://matrix.example.com

Enregistrez le premier compte à l'aide du jeton fourni conduit.toml. Faites-le rapidement après la mise en ligne du service. Si vous ne souhaitez pas d'enregistrements ultérieurs, modifiez la configuration allow_registration = falseet redémarrez le conteneur.

cd /opt/conduit
sudo docker compose restart conduit

Exécutez maintenant trois vérifications depuis n'importe quelle machine pouvant accéder au domaine :

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

La première requête doit renvoyer un JSON décrivant les versions de l'API client Matrix prises en charge. Les requêtes classiques doivent renvoyer des informations de découverte JSON valides. Pour la fédération, utilisez également l' outil de test de fédération Matrix et essayez de rejoindre une salle fédérée depuis le nouveau compte.

Erreurs courantes empêchant le fonctionnement d'un serveur Raspberry Pi Matrix

• Utilisation inutile d'un système d'exploitation 32 bits : pour un Pi 4, utilisez Raspberry Pi OS 64 bits et les paquets Debian ARM64 pris en charge par Docker.
• Exposition directe de Conduit : gardez le port 6167 lié 127.0.0.1sur l’hôte et exposez HTTPS via NGINX.
• Laisser l'enregistrement ouvert sans protection : utilisez un jeton d'enregistrement fort lors de la configuration initiale, puis désactivez l'enregistrement si vous n'en avez plus besoin.
• Publication d'un DNS incorrect : si vous publiez les enregistrements IPv4 et IPv6, ceux-ci doivent pointer vers un point de terminaison fonctionnel.
• Oublier les règles du routeur ou du pare-feu : un conteneur correct ne peut pas compenser le blocage du trafic TCP entrant 80/443.
• En supposant que la messagerie et les appels vocaux soient identiques : la messagerie Matrix peut fonctionner même si les appels échouent. La documentation de Conduit indique que la communication vocale nécessite un serveur TURN tel que Coturn.
• Ignorer les sauvegardes : la FAQ de Conduit recommande d’arrêter Conduit avant d’effectuer une copie classique de sa base de données, sauf si vous utilisez un instantané du système de fichiers. Sauvegardez le volume Docker et votre configuration avant toute mise à niveau.

À quoi ressemble une installation réussie ?

Le processus est terminé lorsque toutes ces conditions sont remplies : le conteneur Conduit reste en fonctionnement après un redémarrage ; https://matrix.example.com/_matrix/client/versionsil renvoie du JSON ; un client Matrix peut s’enregistrer ou se connecter à votre serveur d’accueil personnalisé ; le compte peut créer une salle et envoyer un message ; et, si la fédération est activée, le testeur de fédération peut accéder au serveur et l’utilisateur peut communiquer avec des comptes sur un autre serveur d’accueil.

Pour un petit déploiement sur Raspberry Pi, il s'agit d'une configuration de base simple, et non de la fin de l'administration. Surveillez l'espace de stockage disponible, maintenez à jour Raspberry Pi OS et Docker, sauvegardez la base de données et consultez la documentation officielle de Conduit avant d'activer des fonctionnalités supplémentaires. Conduit reste une option légère et intéressante pour le matériel de type Raspberry Pi, mais son statut bêta est un véritable facteur opérationnel à prendre en compte, et non une simple information.