Si Matrix Synapse sur CasaOS affiche « container is unhealthy », commencez par consulter les journaux du conteneur et le fichier homeserver.yaml généré plutôt que de réinstaller sans réfléchir. Synapse dispose d’une image Docker officielle, mais un homeserver de production nécessite également une configuration et des données persistantes, un nom de serveur approprié, PostgreSQL, ainsi qu’une planification pour HTTPS et la fédération.
SQLite convient pour les tests, mais la documentation actuelle de Synapse recommande PostgreSQL pour presque toutes les installations réelles. Un conteneur peut démarrer tout en restant en état « unhealthy » si sa configuration, sa base de données, ses permissions ou sa migration au démarrage échoue.
Utiliser l’image Synapse officielle
Le guide d’installation de Synapse actuel indique que ghcr.io/element-hq/synapse est une image de conteneur officielle.
Générer la configuration initiale
Créez un répertoire persistant et générez la configuration une fois avant le démarrage normal :
mkdir -p /DATA/AppData/synapse
docker run --rm -it -v /DATA/AppData/synapse:/data -e SYNAPSE_SERVER_NAME=matrix.example.com -e SYNAPSE_REPORT_STATS=no ghcr.io/element-hq/synapse:latest generateRemplacez le domaine d’exemple par le nom de serveur Matrix que vous comptez conserver.
Vérifier pourquoi le conteneur est en état « unhealthy »
docker ps -a | grep synapse
docker inspect synapse --format '{{json .State.Health}}'
docker logs --tail 200 synapseRecherchez les erreurs YAML, les fichiers manquants, les problèmes de permissions, les erreurs de connexion à la base de données ou les migrations qui ne se terminent jamais.
Utiliser PostgreSQL en production
Le guide PostgreSQL de Synapse actuel explique la configuration de base de données prise en charge. Conservez les données PostgreSQL dans un emplacement persistant et sauvegardez-les avec l’état de Synapse.
Ne pas modifier server_name ultérieurement sans préparation
Vos identifiants Matrix sont dérivés du nom du serveur, par exemple @user:example.com. Choisissez le domaine à long terme avant d’inviter des utilisateurs.
HTTPS est nécessaire pour une utilisation pratique
Synapse écoute normalement en interne sur HTTP (généralement le port 8008). Utilisez un proxy inverse avec HTTPS pour les clients et la fédération au lieu d’exposer publiquement le port brut du conteneur.
La fédération ajoute d’autres exigences DNS et de proxy
Si vous souhaitez communiquer avec d’autres serveurs Matrix, configurez correctement le nom de serveur public, HTTPS et la découverte de la fédération. Un test en local uniquement peut être beaucoup plus simple.
Sauvegarder plus que le conteneur
Conservez homeserver.yaml, les clés de signature, les fichiers multimédias importés et la base de données PostgreSQL. Retélécharger l’image ne restaure pas l’identité d’un homeserver.
Le guide de dépannage Docker présente le modèle général de diagnostic des conteneurs.
Vérifier les propriétaires du dossier de données persistant
Si le journal du conteneur indique « permission denied » lors de la lecture de homeserver.yaml, des clés de signature ou des fichiers multimédias, corrigez le propriétaire du répertoire de données Synapse monté afin qu’il corresponde à l’UID/GID attendu par l’image. Évitez de rendre toute l’arborescence de données CasaOS accessible en écriture à tous.
Attendre la fin des migrations de la base de données avant d’évaluer l’état de santé
Après une mise à niveau ou la première connexion à PostgreSQL, Synapse peut avoir besoin de temps pour exécuter les migrations du schéma. Surveillez les journaux au lieu de redémarrer le conteneur à répétition, car des migrations interrompues peuvent compliquer le diagnostic.
Tester l’API locale avant le proxy inverse
Vérifiez que le point de terminaison HTTP interne de Synapse répond depuis l’hôte CasaOS avant d’ajouter HTTPS, le DNS ou la fédération. Si l’API locale n’est pas saine, un proxy inverse ne pourra pas résoudre le problème.
FAQ
Pourquoi Synapse est-il en état « unhealthy » ?
Consultez les journaux et les informations de santé pour rechercher des erreurs de configuration, de permissions, de base de données ou de migration ; le fil d’origine ne fournit pas de cause unique vérifiée.
Puis-je utiliser SQLite ?
Pour les tests, oui. La documentation actuelle de Synapse recommande PostgreSQL pour presque toutes les installations de production.
Quel port Synapse utilise-t-il en interne ?
Les configurations Docker courantes exposent l’API client/serveur sur le port 8008 derrière un proxy inverse.
Ai-je besoin d’Element ?
Non. Synapse est le homeserver ; Element est un client ou une interface web possible.
