Déploiement de Matrix Synapse avec Docker Compose et PostgreSQL

Exécutez Synapse comme un projet Docker Compose avec un répertoire de configuration persistant et une base de données PostgreSQL. La configuration ci-dessous génère les clés de signature de Synapse homeserver.yaml, le connecte à PostgreSQL et maintient l'écouteur HTTP sur localhost afin de pouvoir placer le HTTPS et la fédération derrière un proxy inverse avant d'ouvrir le serveur sur Internet.

Synapse est le serveur principal de Matrix : il stocke les comptes, les salles, les événements et les fichiers multimédias du serveur. Docker Compose exécute les conteneurs Synapse et PostgreSQL à partir d'un seul fichier YAML. Il s'agit d'une configuration initiale pour une seule machine, et non d'un déploiement public complet de Matrix.

Avant de commencer

Installez Docker Engine et le plugin Docker Compose, puis vérifiez son docker compose versionbon fonctionnement. Docker Desktop inclut Compose sur Windows et macOS ; les utilisateurs Linux peuvent installer le plugin Compose depuis le dépôt de paquets Docker. Consultez les instructions d'installation de Docker Compose .

Choisissez le nom permanent du serveur Matrix avant de générer la configuration. Ce nom apparaît dans les identifiants utilisateur, par exemple `<nom_utilisateur>` @alex:matrix.example.org, et sa modification ultérieure ne relève pas d'une simple modification de nom d'hôte. Dans cet exemple, ` matrix.example.org<nom_serveur>` est à la fois le nom du serveur Matrix et le nom d'hôte public. Pour un serveur public, configurez son enregistrement DNS pour qu'il pointe vers votre hôte et prévoyez un proxy inverse HTTPS. L'écouteur HTTP généré par Synapse sur le port 8008 convient aux tests locaux ; sa documentation d'installation indique qu'une utilisation pratique nécessite le protocole HTTPS.

1. Créez un projet et un secret

Sur l'hôte Docker, créez un répertoire de travail et les dossiers persistants. Le synapsepremier dossier contiendra la configuration générée et la clé de signature ; data/postgresle second, les fichiers de base de données.

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

Copiez le résultat de la commande dans un nouveau .envfichier DB_PASSWORD=.... Conservez ce fichier confidentiel et effectuez une sauvegarde sécurisée. Compose utilise .envles substitutions du fichier Compose ; Synapse ne développe pas automatiquement ces variables homeserver.yaml. Vous saisirez le même mot de passe dans ce fichier de configuration à l'étape 3.

Vue illustrative du terminal d'un répertoire de projet matrix-synapse contenant docker-compose.yml, un fichier d'environnement, un dossier de configuration Synapse et un dossier de données.
Un dossier de projet sépare la définition Compose, la configuration Synapse et les fichiers de base de données persistants.

2. Définissez les deux services

Créez ce fichier docker-compose.ymldans le répertoire du projet. Cet exemple utilise l'image Synapse officielle publiée par Element HQ et PostgreSQL 16. Le port Synapse est configuré pour la boucle locale et non pour chaque interface réseau. La vérification d'intégrité permet à Compose d'attendre la disponibilité de PostgreSQL avant de démarrer Synapse.

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

Saisissez la valeur aléatoire obtenue à l'étape 1. Ne versionnez pas ce fichier. Si vous modifiez ultérieurement la version majeure de PostgreSQL, suivez la procédure de mise à niveau de PostgreSQL plutôt que de simplement pointer une image plus récente vers un répertoire de données existant DB_PASSWORD=your-generated-value..env

3. Générez la configuration Synapse et sélectionnez PostgreSQL.

Générez la configuration initiale et la clé de signature dans le synapserépertoire monté. Utilisez le même nom de serveur que celui choisi précédemment. Définissez explicitement le choix des statistiques ; le voicino :

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

Le mode du conteneur officiel generatecrée homeserver.yamlla clé de signature requise. Ouvrez le fichier synapse/homeserver.yamlet remplacez sa section de base de données SQLite par le code suivant. Remplacez PASTE_THE_SAME_DB_PASSWORD_HEREpar la valeur exacte stockée dans .env. Ce champ correspond à une valeur de configuration Synapse littérale, et non à une interpolation Compose.

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
Vue illustrative de l'éditeur homeserver.yaml avec PostgreSQL configuré via psycopg2, la base de données synapse, la base de données hôte, le port 5432 et un pool de connexions.
La section relative à la base de données Synapse pointe vers le nom du service Compose, db, sur le port interne de PostgreSQL.

Conservez le fichier généré registration_shared_secretprivé. Synapse l'utilise pour son outil d'inscription en ligne de commande ; toute personne qui l'obtient peut créer des comptes, y compris les administrateurs. Désactivez l'inscription publique, sauf si vous souhaitez l'activer et que vous avez pris connaissance des mesures de contrôle des abus.

4. Démarrez Synapse et consultez les journaux.

Depuis le répertoire contenant docker-compose.yml, validez le fichier Compose et démarrez les services :

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

La première commande vérifie que Compose peut analyser le fichier et le résoudre DB_PASSWORD. La suivante démarre la base de données et le serveur d'accueil en arrière-plan. Consultez les journaux pour détecter d'éventuelles erreurs de connexion à la base de données ou un fichier de configuration manquant. Grâce au montage des répertoires locaux, la configuration de la base de données et de Synapse est conservée lors de la recréation des conteneurs.

Exemple d'invite de commande du terminal avec la commande docker compose up -d saisie pour démarrer la pile Synapse.
Démarrez les services Synapse et PostgreSQL après avoir généré et vérifié la configuration.

5. Vérifiez le point de terminaison local et créez un compte

Exécutez la requête de versions du client Matrix depuis l'hôte Docker. Une réponse JSON indique que l'API client répond ; une réponse vide, un refus de connexion ou une erreur HTTP signifie que vous devez consulter les journaux Synapse et vérifier que le port 8008 est ouvert.

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

Une fois la réponse obtenue, créez un utilisateur initial de manière interactive. Cette commande vous demandera un nom d'utilisateur et un mot de passe ; choisissez « non » pour l'administrateur, sauf si vous avez spécifiquement besoin d'un compte administrateur.

docker compose exec synapse register_new_matrix_user \
  -c /data/homeserver.yaml http://localhost:8008
Exemple d'invite de terminal avec une requête curl adressée au point de terminaison des versions du client Matrix de Synapse sur le port 8008 de l'hôte local.
Une réponse positive du point de terminaison des versions confirme que Synapse répond localement ; cet exemple d’invite illustre la vérification, et non un résultat de test.

Rendez-le accessible en toute sécurité

Le mappage de port limité à localhost est intentionnel : il empêche l’accès public direct à l’écouteur HTTP non chiffré. Pour les clients distants, configurez un proxy inverse avec un certificat TLS valide et transmettez les chemins Matrix à Synapse. Le proxy doit transmettre les en X-Forwarded-For- X-Forwarded-Prototêtes ; dans la configuration d’écoute générée, activez le protocole x_forwarded: truepour le port 8008. Ne configurez pas un écouteur Synapse conteneurisé pour qu’il se lie uniquement à 127.0.0.1ce port, car cela empêcherait un conteneur proxy de l’atteindre. Si le proxy inverse est également conteneurisé, placez-le, ainsi que Synapse, sur un réseau Docker partagé et configurez le proxy pour qu’il pointe vers le nom de service synapse:8008.

La fédération est indépendante du démarrage local. Les autres serveurs Matrix doivent détecter et accéder à votre serveur, généralement sur le port 8448 ou via la découverte HTTPS déléguée. Le DNS, le routage du proxy inverse et tous les enregistrements nécessaires doivent correspondre au nom de serveur choisi. Consultez la documentation et les instructions d'installation du proxy inverse.well-known de Synapse avant de rendre votre serveur public. Les appels vocaux et vidéo nécessitent également un serveur TURN pour une connectivité multimédia fiable.

Si Synapse ne parvient pas à se connecter à PostgreSQL, vérifiez que le nom du service Compose hostest dbcorrect, que les deux mots de passe correspondent exactement et que le conteneur de base de données est opérationnel. Si le point de terminaison est inaccessible, consultez docker compose psles journaux de Synapse et vérifiez si un autre service utilise déjà le port 8008. Sauvegardez le répertoire de données PostgreSQL ainsi que la configuration et la clé de signature de Synapse ; cette dernière est essentielle à l'identité du serveur.

Pour plus de détails sur la configuration de PostgreSQL, consultez le guide PostgreSQL de Synapse . Pour les options de conteneur et la création d'utilisateurs, reportez-vous à la documentation officielle Docker de Synapse .

Laisser un commentaire

Déploiement de Matrix Synapse avec Docker Compose et PostgreSQL

Déploiement de Matrix Synapse avec Docker Compose et PostgreSQL

Configurez un serveur Synapse persistant avec Docker Compose, PostgreSQL, une configuration privée et des vérifications avant de l'exposer via HTTPS.

Personnalisez le thème et l'image de marque d'Element Web

Définissez un nom de marque, des couleurs personnalisées et des éléments de connexion pour votre déploiement Element Web tout en identifiant les éléments qui restent de marque Element.

Augmenter la limite de fichiers systemd de Synapse sans tâtonnement

Augmenter la limite de fichiers systemd de Synapse sans tâtonnement

Déterminez si Synapse a atteint sa limite de fichiers ouverts par processus, configurez un module systemd pour le service ou le processus approprié et vérifiez la limite en temps réel.

L'élément affiche « Échec du décryptage » ? Restaurez la clé de la pièce manquante

L'élément affiche « Échec du décryptage » ? Restaurez la clé de la pièce manquante

Déterminez si l'erreur est limitée à un navigateur ou à un événement, puis utilisez la clé de récupération d'Element ou un appareil de confiance sans risquer de perdre votre historique chiffré restant.

Nettoyez vos anciens messages et fichiers multimédias Synapse sans perdre de données.

Utilisez les API d'historique et de purge multimédia de Synapse ou les paramètres de rétention pour supprimer les données obsolètes en toute sécurité, puis vérifiez l'achèvement de l'opération et la récupération de l'espace disque.

Créez un robot Matrix Echo en Python avec Simple-Matrix-Bot-Lib

Créez un robot Matrix Echo en Python avec Simple-Matrix-Bot-Lib

Installez la bibliothèque actuelle, connectez un compte Matrix dédié et exécutez un petit bot !echo avec une gestion des identifiants plus sûre et un test clair.

Connectez Matrix à WhatsApp, Telegram et Discord via des ponts séparés.

Connectez Matrix à WhatsApp, Telegram et Discord via des ponts séparés.

Configurez trois ponts Mautrix avec des enregistrements, des connexions et des tests distincts, et évitez ainsi les surprises liées au réseau Docker, aux politiques de compte et à la synchronisation.

Récupérez de l'espace disque sur Synapse Media sans endommager les fichiers partagés

Découvrez ce qui occupe l'espace de stockage de Synapse, définissez une durée de conservation des médias sécurisée et purgez le cache distant sans supprimer directement les fichiers du disque.

Désactiver les utilisateurs inactifs de Matrix sans supprimer l'historique des salles

Désactiver les utilisateurs inactifs de Matrix sans supprimer l'historique des salles

Consultez l'activité des appareils, désactivez les comptes Synapse inactifs confirmés via l'API d'administration et découvrez ce que supprime réellement l'option d'effacement.

Réduire la pression sur la mémoire de PostgreSQL dans Matrix Synapse

Déterminez si la mémoire utilisée par PostgreSQL provient des requêtes, des tampons partagés, des connexions ou de la maintenance, puis apportez des modifications ciblées compatibles avec Synapse.