Comment installer Synapse Matrix Server avec Docker Compose

Exemple illustratif : Imaginez un petit groupe de bénévoles souhaitant installer son propre serveur Matrix à l’adresse indiquée chat.example.com. Il s’agit d’une configuration hypothétique, et non d’un compte rendu de test. La même procédure peut être adaptée à un domaine réel, mais choisissez soigneusement le nom du serveur Matrix : Synapse l’utilise dans les identifiants des utilisateurs et il ne pourra plus être modifié ultérieurement.

Ce guide explique comment créer un service Synapse et une base de données PostgreSQL avec Docker Compose. L'image Docker officielle de Synapse utilise SQLite par défaut, ce qui est pratique pour un test rapide ; la documentation Docker de Synapse recommande PostgreSQL pour la production. Cet exemple génère donc d'abord la configuration de Synapse, modifie ses paramètres de base de données pour PostgreSQL, puis démarre les deux conteneurs. L'image officielle est disponible ici : [insérer l'image officielle] ghcr.io/element-hq/synapse. Les instructions et les détails de l'image ont été vérifiés par rapport à la documentation officielle en vigueur le 6 octobre 2026 ; les étiquettes de l'image et les versions logicielles prises en charge peuvent changer, il est donc conseillé de consulter la documentation associée avant un déploiement à long terme.

Ce dont vous avez besoin avant l'installation

• Un serveur Linux ou un autre hôte compatible avec Docker, disposant de Docker Engine et du plugin Docker Compose, est requis. Vérifiez que Compose est disponible docker compose version. Suivez les instructions d'installation officielles de Docker pour votre système d'exploitation.
• Un domaine ou un sous-domaine pointant vers le serveur. Dans cet exemple, chat.example.comil s'agit du nom du serveur Synapse ; les identifiants des utilisateurs locaux ressembleront donc à ceci : @alex:chat.example.com. Remplacez-le par un domaine que vous contrôlez avant de générer la configuration.
• Un proxy inverse ou une autre méthode de terminaison TLS pour une utilisation publique. L'écouteur HTTP par défaut de Synapse sur le port 8008n'est pas un point de terminaison HTTPS accessible depuis Internet. Cet exemple Compose lie ce port à l'interface de bouclage de l'hôte afin qu'un proxy inverse sur la même machine puisse y accéder.

Le nom affiché SYNAPSE_SERVER_NAMEn'est pas nécessairement l'URL de chaque connexion client. Si vous souhaitez des identifiants plus courts, par exemple @alex:example.compour les clients de l'URL spécifiée chat.example.com, cela nécessite une configuration spécifique du domaine et de la découverte. Prenez cette décision avant de créer les comptes.

1. Créez un répertoire de travail et un mot de passe de base de données

Sur le serveur, créez un répertoire pour le projet Compose et les fichiers Synapse persistants :

mkdir -p ~/matrix-synapse/data
cd ~/matrix-synapse

Créez un fichier local .envque Docker Compose pourra lire. Générez un mot de passe long et aléatoire à l'aide d'un gestionnaire de mots de passe ou d'un générateur sécurisé local, et placez-le après le point POSTGRES_PASSWORD=d'entrée. Utilisez des lettres et des chiffres pour cet exemple afin d'éviter les problèmes de guillemets YAML ultérieurement. Ne publiez pas ce fichier dans un dépôt public et limitez ses permissions.

umask 077
nano .env

Le fichier doit contenir une seule ligne, par exemplePOSTGRES_PASSWORD=replace-with-a-long-random-value : « mot de passe ». Ce texte est un espace réservé et non un mot de passe réutilisable. Conservez le mot de passe pour la configuration de la base de données Synapse à l’étape 3.

2. Définir les services Synapse et PostgreSQL

Créer compose.yamldans le répertoire du projet :

services:
  postgres:
    image: postgres:16
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD:?Set POSTGRES_PASSWORD in .env}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 20s

  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      SYNAPSE_SERVER_NAME: chat.example.com
      SYNAPSE_REPORT_STATS: "no"
    volumes:
      - ./data:/data
    ports:
      - "127.0.0.1:8008:8008"

volumes:
  postgres_data:

Remplacez chat.example.compar le nom de serveur final que vous avez choisi. La vérification d'intégrité de PostgreSQL permet à Compose d'attendre que la base de données soit prête avant de démarrer Synapse. Le volume de base de données nommé et le ./datarépertoire monté sur l'hôte sont conservés même après le remplacement des conteneurs ; la simple suppression des conteneurs ne les efface pas. Évitez cette opération, docker compose down -vsauf si vous souhaitez supprimer intentionnellement le volume de base de données.

L'exemple décrit ici :latestsimplifie la première extraction. Pour un serveur maintenu, sélectionnez et enregistrez une étiquette de version Synapse ou un condensé d'image spécifique, puis mettez-le à jour via une procédure de mise à niveau planifiée après avoir consulté les notes de version. Ne présumez pas que l' latestétiquette modifiable conservera la même version.

3. Générez la configuration de Synapse et configurez-la pour qu'elle pointe vers PostgreSQL.

Exécutez l'image officielle une fois en mode de génération de configuration. Étant donné que Compose s'installe ./datasur le répertoire /data`/etc/compose`, la configuration générée et la clé de signature restent sur l'hôte.

docker compose run --rm synapse generate

Cette commande utilise le nom du serveur et l'option de statistiques anonymes définies dans l'environnement Compose. Synapse génère également une clé de signature ; conservez-la dans le répertoire de données et incluez-la dans vos sauvegardes protégées. Ne la régénérez pas et ne la supprimez pas lors d'une mise à jour classique du conteneur.

Ouvrez data/homeserver.yamlet remplacez la section générée database:par les paramètres suivants. Utilisez le mot de passe exact à .envla place de l'espace réservé :

database:
  name: psycopg2
  args:
    user: synapse
    password: 'replace-with-the-same-random-value'
    dbname: synapse
    host: postgres
    port: 5432
    cp_min: 5
    cp_max: 10

Conservez l'indentation YAML et assurez-vous qu'il n'y ait qu'une seule database:section active. Le nom d'hôte postgrescorrespond au nom du service Compose, que les conteneurs peuvent résoudre sur leur réseau par défaut partagé. La configuration utilise le nom du moteur PostgreSQL documenté par Synapse, psycopg2ainsi que les noms des arguments de base de données dbname.

Dans cet exemple simple, le mot de passe de la base de données apparaît à la fois dans la configuration Synapse et dans le .envfichier protégé. Traitez ces deux fichiers comme des secrets, limitez l'accès à l'hôte et utilisez une méthode de gestion des secrets dédiée si votre environnement de déploiement l'exige. Ne collez jamais le mot de passe réel dans les journaux, les captures d'écran ou les demandes d'assistance.

4. Démarrer Synapse avec Docker Compose

Démarrez la pile en arrière-plan :

docker compose up -d

Vérifiez l'état du service et consultez les journaux de démarrage :

docker compose ps
docker compose logs --tail=100 synapse

Attendez que Synapse termine la configuration initiale de sa base de données. Un conteneur en cours d'exécution signifie seulement que son processus est actif ; consultez les journaux pour détecter d'éventuelles erreurs de configuration, de base de données ou d'autorisation avant de continuer. Pour suivre les journaux en temps réel, utilisez la commande appropriée docker compose logs -f synapseet appuyez sur la touche Ctrl+Ccorrespondante pour arrêter le suivi sans interrompre le conteneur.

5. Vérifiez l'API locale et configurez l'accès public.

Depuis l'hôte Docker, demandez le point de terminaison des versions de l'API client de Synapse :

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

Une réponse positive est un JSON décrivant les versions de l'API client Matrix prises en charge. Cela confirme que l'écouteur HTTP répond localement ; cela ne prouve pas que le DNS, le HTTPS ou la fédération sont correctement configurés.

Configurez le proxy inverse hôte pour rediriger les requêtes vers le domaine choisi http://127.0.0.1:8008et obtenez un certificat TLS valide. Préservez le chemin de requête Matrix lors de la mise en place du proxy. Vérifiez ensuite le point de terminaison public :

curl -fsS https://chat.example.com/_matrix/client/versions

Remplacez le nom d'hôte d'exemple par le vôtre. Si les clients doivent découvrir le serveur d'accueil depuis un domaine d'identifiant utilisateur distinct, publiez les enregistrements de découverte connus Matrix appropriés. La fédération requiert également un routage public et un DNS corrects ; l'ouverture d'un port local 8008ne suffit pas à un déploiement public complet. Consultez les recommandations de Synapse concernant le proxy inverse et la fédération avant d'exposer le service.

6. Créez le premier compte administrateur

Synapse désactive l'enregistrement public par défaut. Pour un serveur privé, conservez ce paramètre et créez les comptes en ligne de commande. Ajoutez temporairement une registration_shared_secretvaleur forte à `<nom_du_domaine>` data/homeserver.yaml, puis redémarrez Synapse pour que la modification soit prise en compte.

docker compose restart synapse

Exécutez l'outil d'enregistrement dans le conteneur. Il vous demandera un nom d'utilisateur et un mot de passe ; cette opération --admincréera le premier administrateur.

docker compose exec synapse register_new_matrix_user \
  http://localhost:8008 \
  -c /data/homeserver.yaml \
  --admin

Une fois le compte créé, supprimez-le registration_shared_secretde la configuration et redémarrez Synapse. Si le secret est conservé, toute personne qui l'obtient pourra créer des comptes standard ou administrateur via l'interface d'inscription. Connectez-vous via un client Matrix compatible avec les serveurs d'accueil personnalisés, en utilisant l'URL du serveur fournie par votre proxy inverse.

Sauvegardes, mises à niveau et correctifs courants

• Sauvegardez les données essentielles : effectuez des sauvegardes régulières ou arrêtez le processus PostgreSQL ./data, y compris la configuration, les supports de stockage et la clé de signature. Une compose.yamlsimple copie de ces données ne suffit pas à restaurer le serveur. Stockez vos sauvegardes séparément du serveur et vérifiez régulièrement que vous pouvez y accéder.
• Synapse ne peut pas écrire dans ce répertoire/data : vérifiez les droits d'accès et les permissions de l'hôte ./data. L'utilisateur d'exécution de l'image officielle doit avoir l'autorisation de lire la configuration et d'écrire des données. Modifiez les droits d'accès avec précaution plutôt que de rendre le répertoire accessible en écriture à tous.
• Échec de la connexion à la base de données : vérifiez que la configuration de la base de données utilise l’URL appropriée host: postgres, que le mot de passe correspond .envet que docker compose logs postgresla base de données est saine. depends_onLa condition de disponibilité de Compose réduit les conflits d’accès au démarrage, mais ne corrige pas les informations d’identification incorrectes.
• L'API locale fonctionne, mais les clients ne peuvent pas se connecter : vérifiez l'enregistrement DNS, le certificat TLS, le proxy inverse en amont et les enregistrements de découverte pour votre configuration de domaine. Le mappage du port de bouclage uniquement est intentionnel pour un proxy sur le même hôte ; un proxy dans un autre conteneur nécessite un réseau Docker partagé et une architecture de routage différente.
• Mise à niveau : effectuez d’abord une sauvegarde, consultez les notes de version de Synapse, mettez à jour l’étiquette de l’image épinglée et recréez le service . Conservez le même répertoire de données, le même volume de base de données, le docker compose pullmême docker compose up -dnom de serveur et la même clé de signature.

Dans l'exemple de configuration avec un groupe de bénévoles, l'installation est considérée comme terminée uniquement lorsque le point de terminaison des versions locales répond, que le point de terminaison HTTPS répond via le proxy et que l'administrateur peut se connecter à l'aide du domaine Matrix ID prévu. Ces vérifications sont des indicateurs pratiques du bon fonctionnement du premier déploiement ; elles ne remplacent pas l'examen des exigences de sécurité, de sauvegarde, de fédération et d'exploitation avant d'inviter une communauté plus large.

Références officielles

• Instructions d'installation de Synapse et guide sur le nom du serveur
• README de l'image Docker officielle de Synapse
• Référence de configuration Synapse
• Guidage par proxy inverse de Synapse
• Installation de Docker Engine
• Ordre de démarrage et vérifications de l'état de santé de Docker Compose