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.
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.
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.
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.

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
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

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.
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.

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

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 .
Configurez un serveur Synapse persistant avec Docker Compose, PostgreSQL, une configuration privée et des vérifications avant de l'exposer via HTTPS.
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.
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.
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.
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.
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.
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.
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.
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.
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.