Dépannage

Cette page recense les pannes qui arrivent vraiment sur une instance auto-hébergée, dans l’ordre où on les rencontre : déploiement, installation, accès, email, live, puis exploitation. Chaque section donne le symptôme observable, sa cause dans les descriptifs livrés, et la correction.

Avant de chercher une panne précise, regardez l’état des conteneurs. Sur le parcours Coolify, l’onglet de la ressource affiche l’état de chaque service et ses journaux. Sur le parcours Docker Compose :

docker compose --env-file infra/compose/.env -f infra/compose/docker-compose.yml ps
docker compose --env-file infra/compose/.env -f infra/compose/docker-compose.yml logs --tail 200 backend
docker compose --env-file infra/compose/.env -f infra/compose/docker-compose.yml exec backend wget -q -O - http://127.0.0.1:3000/healthz

La sonde /healthz passe par docker compose exec parce que le Compose standalone ne publie pas le port du backend sur l’hôte.

Le domaine répond 504 après un déploiement Coolify

Symptôme. Le déploiement se termine, les conteneurs tournent, mais le domaine renvoie une erreur de passerelle du proxy Coolify.

Cause. Le template a été modifié. Coolify branche lui-même les conteneurs sur le réseau de son proxy : une section networks: ajoutée à la main, un build: ou un extends: cassent ce branchement. Le contrôle infra/coolify/validate-template.sh refuse d’ailleurs explicitement ces trois clés dans le descriptif.

Correction. Repartez du fichier livré infra/coolify/docker-compose.yaml sans y ajouter de réseau, puis redéployez. Vérifiez ensuite que le domaine est bien assigné au bon service et au bon port : SERVICE_FQDN_BACKEND pour l’API et SERVICE_URL_WEB pour l’interface, deux variables Coolify décrites dans Déployer avec Coolify.

La base repart vide à chaque redémarrage

Symptôme. Après un redémarrage, l’instance propose à nouveau le wizard d’installation, ou les contenus créés la veille ont disparu.

Cause. Le point de montage du volume Postgres a été changé. Les deux descriptifs livrés montent le volume de données sur /var/lib/postgresql, et l’image Postgres 18 embarquée n’utilise plus le chemin /var/lib/postgresql/data des versions précédentes. Un volume monté sur l’ancien chemin ne contient donc pas les données réellement écrites par le serveur : elles vivent dans la couche éphémère du conteneur et disparaissent avec lui.

Correction. Rétablissez le montage du descriptif livré, puis restaurez la dernière archive en suivant Restaurer une instance. Les données écrites depuis une couche éphémère perdue ne sont pas récupérables autrement.

Rien ne répond sur le domaine en Docker Compose

Symptôme. La stack est démarrée et ps montre les services healthy, mais le navigateur n’obtient aucune réponse sur le domaine.

Cause. Le Compose pivot ne publie aucun port sur l’hôte en dehors du profil caddy. Sans ce profil et sans proxy branché sur le réseau interne, rien n’écoute sur 80 ni sur 443.

Correction. Deux options, détaillées dans Déployer avec Docker Compose : activer le profil caddy avec CADDY_DOMAIN pour obtenir le TLS automatique, ou brancher votre propre proxy sur le réseau interne de la stack. Les en-têtes de sécurité HTTP sont portés par le backend, pas par le proxy : un proxy tiers n’a rien à ajouter de ce côté.

Le wizard refuse le domaine saisi

Symptôme. Le premier écran du wizard d’installation bloque sur la vérification du domaine.

Cause. Le wizard résout le domaine avant de continuer et retourne un code stable :

Code	Signification
DNS_A_RECORD_NOT_FOUND	Aucun enregistrement A trouvé pour ce domaine
DNS_TARGET_MISMATCH	Le domaine résout, mais vers une autre adresse que celle attendue
DNS_LOOKUP_FAILED	La résolution n’a pas abouti (réseau, registrar, propagation)
INSTALL_DOMAIN_INVALID	La valeur saisie n’est pas un nom public valide

DNS_TARGET_MISMATCH n’apparaît que si l’instance déclare son adresse publique via INSTALL_EXPECTED_HOST_IP, une variable du parcours Docker Compose ; le template Coolify ne la déclare pas, et la vérification s’y limite donc à l’existence de l’enregistrement. Quand elle est renseignée, le message indique les adresses trouvées et celle attendue.

Correction. Créez ou corrigez l’enregistrement A chez votre registrar, attendez la propagation, puis relancez la vérification depuis le wizard. Un nom de machine local ou une adresse IP nue sont rejetés : le domaine doit être public.

Le wizard répond « un administrateur existe déjà »

Symptôme. Le wizard renvoie INSTALL_ADMIN_ALREADY_EXISTS au moment de créer le compte administrateur.

Cause. L’instance est déjà installée. Le wizard ne rejoue pas la création du premier compte : c’est une protection contre la prise de contrôle d’une instance en ligne par un visiteur.

Correction. Connectez-vous avec le compte administrateur existant. Si personne ne peut plus s’y connecter, utilisez la procédure de récupération d’accès plutôt que de réinstaller. Réinstaller depuis une base vide effacerait la communauté.

Plus aucun administrateur ne peut se connecter

Symptôme. Mot de passe perdu, second facteur inaccessible, ou téléphone d’authentification remplacé.

Cause. La double authentification administrateur ne se contourne pas depuis l’interface.

Correction. Suivez Récupérer un accès administrateur : c’est cette page qui donne la forme exacte de la commande. Lancé tel quel, le wrapper cenaclo-admin-recover.sh sort en code 2 : il démarre un processus neuf, qui n’hérite pas des fichiers d’environnement chargés au démarrage du service, donc ni des secrets générés au premier boot, ni de la configuration Listmonk. La forme corrigée recharge ces deux fichiers sur la ligne de commande elle-même. Les autres sorties sont 0 en cas de succès, 1 pour un usage invalide ou une cible introuvable et 3 pour une erreur technique.

La récupération a besoin d’un envoi d’email fonctionnel

La procédure réinitialise le second facteur puis envoie un email au compte visé. Sans SMTP configuré, elle s’arrête à mi-chemin. Traitez d’abord la section suivante.

Aucun email transactionnel ne part

Symptôme. Les invitations, vérifications d’adresse et emails de récupération n’arrivent jamais. Le journal /admin/emails affiche des envois en statut failed.

Cause. Aucune configuration SMTP n’est fournie. Sur le parcours Coolify, LISTMONK_SEED_SMTP_MODE vaut skip par défaut pour que le premier déploiement soit autonome : l’instance démarre, mais elle n’a pas de serveur d’envoi. Cenaclo n’embarque pas de service d’envoi ; l’opérateur fournit le sien.

Correction. Renseignez vos identifiants SMTP puis relancez la configuration, en suivant Emails et SMTP. Vérifiez ensuite SPF, DKIM et DMARC sur le domaine d’envoi : un message parti en statut sent mais jamais reçu est presque toujours un problème d’authentification de domaine, pas de configuration Cenaclo.

Le live ne s’ouvre pas dans le navigateur en Docker Compose

Symptôme. Le salon en direct se crée, mais aucun participant n’établit la connexion média. La console du navigateur montre une tentative de connexion vers une adresse interne.

Cause. LIVEKIT_PUBLIC_URL est vide par défaut. Le backend retombe alors sur l’URL interne LIVEKIT_URL, qui vaut ws://livekit:7880 : elle est résolvable entre conteneurs, jamais depuis un navigateur. Le Compose ne publie pas non plus les ports média sur l’hôte.

Correction. Exposez LiveKit publiquement, renseignez LIVEKIT_PUBLIC_URL avec l’URL wss:// publique et ouvrez les ports correspondants, comme décrit dans Déployer avec Docker Compose. Le parcours Coolify fait ce câblage en assignant un domaine au service livekit.

Aucun replay n’est produit après un live

Symptôme. Le direct se déroule normalement, mais aucun enregistrement n’apparaît ensuite.

Cause. Le conteneur d’enregistrement charge une page de composition qui refuse les hôtes non déclarés. CENACLO_LIVE_EGRESS_ALLOWED_HOSTS vaut livekit:7880 par défaut, ce qui couvre le LiveKit embarqué. Avec un serveur LiveKit externe, ou après un changement d’URL interne, la liste ne contient plus l’hôte réellement joint et la page est refusée.

Correction. Alignez CENACLO_LIVE_EGRESS_ALLOWED_HOSTS sur l’hôte réellement utilisé par l’enregistreur, puis relancez un live de test. Les deux valeurs se changent ensemble : l’URL du serveur LiveKit et la liste d’hôtes autorisés.

Le son et la vidéo ne passent pas depuis certains réseaux

Symptôme. Le live fonctionne depuis chez vous mais pas depuis un réseau d’entreprise ou un hôtel : la connexion s’établit puis reste muette.

Cause. Ces réseaux filtrent le trafic UDP sortant. Sans relais TURN joignable, aucun flux média ne peut être négocié.

Correction. Le relais TURN mutualisé est le chemin recommandé et ne demande aucune configuration. Si vous administrez votre propre relais avec le profil coturn, ouvrez le range UDP 49152-65535 sur le firewall du serveur : les ports de signalisation seuls ne suffisent pas. Le détail des ports est dans Firewall self-hosting.

La seconde ressource Coolify refuse de démarrer sur le même serveur

Symptôme. Une deuxième instance déployée sur la même machine échoue au démarrage sur un conflit de port.

Cause. Dans le template Coolify, les ports média LiveKit sont publiés sur l’hôte avec des valeurs fixes, 7881/tcp et 7882/udp. Deux ressources ne peuvent pas les partager.

Correction. Donnez à la seconde ressource une autre paire via LIVEKIT_RTC_TCP_PORT et LIVEKIT_RTC_UDP_PORT, et ouvrez les nouveaux ports sur le firewall. Le dimensionnement de ce scénario est traité dans Dimensionner le serveur.

Deux stacks Compose écrivent dans les mêmes volumes

Symptôme. Une seconde stack démarrée sur le même serveur affiche la communauté de la première, ou la première perd ses données après le démarrage de la seconde.

Cause. Le fichier livré ne publie aucun port média, donc rien ne signale le conflit : le nom du réseau et ceux des onze volumes y sont fixes, sans préfixe d’instance. Un second up -d depuis le même fichier réutilise les mêmes volumes, dont celui de Postgres, même avec un autre nom de projet.

Correction. Avant de démarrer la seconde stack, donnez-lui son propre nom de projet, son propre réseau et ses propres volumes, avec COMPOSE_PROJECT_NAME, INTERNAL_NETWORK_NAME et les variables *_VOLUME_NAME. La liste complète des points à changer est dans Dimensionner le serveur.

La mise à jour par script échoue sur une ressource Coolify

Symptôme. cenaclo-update.sh ne trouve pas le descriptif attendu, ou la mise à jour est écrasée au déploiement suivant.

Cause. Ce script appartient au parcours Docker Compose : il attend un fichier Compose local, via --compose-file ou COMPOSE_FILE. Sur une ressource Coolify, c’est Coolify qui possède le pull, le redémarrage progressif et la vérification de santé.

Correction. Sur Coolify, changez le tag d’image puis lancez un déploiement, ou déclenchez le webhook configuré. Sur Compose, utilisez le script avec ses options explicites. Les deux procédures sont décrites dans Mettre à jour.

La restauration s’arrête sur le déchiffrement

Symptôme. cenaclo-restore.sh s’interrompt avec une erreur de déchiffrement de l’archive.

Cause. La passphrase fournie n’est pas celle qui a chiffré l’archive. Elle est lue depuis CENACLO_BACKUP_PASSPHRASE_FILE ou CENACLO_BACKUP_PASSPHRASE. Sur le parcours Coolify, cette valeur est alimentée par le secret généré SERVICE_PASSWORD_64_BACKUP de la ressource : elle est propre à l’instance qui a produit l’archive.

Correction. Récupérez la passphrase de l’instance d’origine, pas celle de l’instance de destination, et fournissez-la par fichier plutôt qu’en variable lorsque c’est possible. Sans elle, l’archive est définitivement illisible : voir Restaurer une instance.

La restauration refuse une archive d’une autre version majeure

Symptôme. La restauration s’arrête en signalant une différence de version majeure, ou une version absente du manifeste.

Cause. L’archive porte la version de l’instance qui l’a produite. Restaurer une archive d’une autre version majeure sur le schéma courant peut corrompre les données ; le script s’y refuse par défaut.

Correction. Déployez d’abord la version correspondant à l’archive, puis laissez les migrations s’appliquer au démarrage. Si vous avez validé la compatibilité de schéma, l’option --force lève le contrôle. Les cas exacts sont détaillés dans Restaurer une instance.

Après restauration, des contenus chiffrés restent illisibles

Symptôme. L’instance restaurée démarre, les comptes et les contenus sont là, mais certaines données chiffrées au repos ne s’ouvrent pas.

Cause. Les secrets générés à l’installation ne sont pas dans l’archive : ils vivent dans un volume dédié du serveur, et le fichier de configuration sauvegardé est expurgé de toute valeur sensible. Une instance de destination qui a régénéré ses propres secrets ne peut pas déchiffrer les données de l’instance d’origine.

Correction. Restaurez sur une instance qui possède les mêmes secrets d’installation, ou reportez-les avant la restauration. Cette limite est documentée avec la procédure complète dans Restaurer une instance et dans Sauvegardes self-hosting.