Déployer avec Coolify

Coolify est le parcours recommandé pour auto-héberger Cenaclo. C’est un PaaS open source que vous installez sur votre propre serveur : il porte le reverse proxy, les certificats TLS Let’s Encrypt, la génération des secrets, le redéploiement et les tâches planifiées. Vous n’avez donc ni fichier .env à remplir, ni proxy à configurer à la main.

Si vous préférez piloter Docker vous-même, le parcours Docker Compose reste entièrement supporté.

Ce que Coolify prend en charge, et ce qu’il ne prend pas

Pris en charge par Coolify	À votre charge
Reverse proxy Traefik et TLS Let’s Encrypt	Enregistrements DNS du domaine
Génération et stockage des secrets SERVICE_PASSWORD_*	Conservation hors serveur de la passphrase de backup
Redéploiement, rollback, historique des déploiements	Choix de la version applicative à déployer
Tâches planifiées (backup, purge de rétention)	Sauvegarde des archives hors du serveur
Journaux et état de santé des conteneurs	Ouverture du firewall pour le média LiveKit

Coolify ne remplace pas la sauvegarde applicative Cenaclo : ses sauvegardes Postgres natives ne chiffrent pas avec la passphrase de l’installation et ne couvrent pas les volumes de stockage objet. Voir Sauvegardes self-hosting.

Prérequis

1. Une instance Coolify fonctionnelle. L’installation de Coolify elle-même suit la procédure officielle du projet Coolify et sort du périmètre de cette documentation.
2. Un domaine dont les enregistrements DNS pointent vers le serveur Coolify. Prévoyez un enregistrement A (ou AAAA) par service exposé : l’application web, l’API et le serveur LiveKit.
3. Un serveur suffisamment dimensionné. Coolify tourne sur la même machine que Cenaclo : additionnez les deux empreintes. Voir Dimensionner le serveur.
4. Un accès au registre Docker Hub privé zeross pendant la phase de préversion. Les images de distribution ne sont pas encore publiques ; ajoutez le registre dans Coolify avec un jeton en lecture seule. Cette étape disparaîtra quand les images seront publiées.

1. Créer la ressource

1. Créez un projet dans Coolify, puis ajoutez une ressource de type Docker Compose Empty.
2. Collez le contenu de infra/coolify/docker-compose.yaml du dépôt Cenaclo.
3. Laissez le déploiement en mode Compose géré par Coolify. N’activez pas le mode raw.

Le template est autonome : il ne clone pas le dépôt, ne construit aucune image et ne dépend d’aucun fichier relatif. Il tire les images versionnées zeross/cenaclo:backend-<version> et zeross/cenaclo:web-<version>, ainsi que les images amont des services d’infrastructure.

N’ajoutez pas de section networks:

Coolify crée son propre réseau isolé et y connecte Traefik. Un réseau Compose personnalisé peut faire router Traefik vers une adresse non joignable et provoquer des erreurs 504 intermittentes.

2. Assigner les domaines

Après le chargement du Compose, Coolify détecte trois services déployables : web, backend et livekit. Assignez un domaine à chacun dans l’interface Coolify, en précisant le port du conteneur.

Service	Domaine à saisir dans Coolify	Port conteneur
web	https://app.example.com	80
backend	https://api.example.com:3000	3000
livekit	https://live.example.com:7880	7880

Coolify injecte alors les variables suffixées par le port, puis expose les alias publics sans suffixe :

SERVICE_URL_WEB_80=https://app.example.com
SERVICE_FQDN_WEB_80=app.example.com
SERVICE_URL_WEB=https://app.example.com
SERVICE_FQDN_WEB=app.example.com
SERVICE_URL_BACKEND_3000=https://api.example.com
SERVICE_FQDN_BACKEND_3000=api.example.com
SERVICE_URL_BACKEND=https://api.example.com
SERVICE_FQDN_BACKEND=api.example.com
SERVICE_URL_LIVEKIT_7880=https://live.example.com
SERVICE_FQDN_LIVEKIT_7880=live.example.com
SERVICE_URL_LIVEKIT=https://live.example.com
SERVICE_FQDN_LIVEKIT=live.example.com

Les variables suffixées existent pour que Coolify connaisse le port cible. Les applications ne consomment que les alias sans suffixe : le port du conteneur ne doit jamais apparaître dans une URL envoyée au navigateur. Le template transmet SERVICE_FQDN_BACKEND au backend afin que le wizard d’installation préremplisse le bon domaine public, et CENACLO_API_BASE_URL=${SERVICE_URL_BACKEND} au service web pour que la SPA appelle l’API sur son domaine dédié.

Pas de service caddy dans Coolify

Coolify et Traefik terminent déjà TLS et routent le trafic. Ajouter un second proxy dans la ressource crée un double proxy inutile et difficile à déboguer. Les en-têtes HTTP de sécurité restent servis par le backend Fastify, quel que soit le proxy placé devant.

Ports média LiveKit

Le média WebRTC ne passe pas par le proxy HTTP. Ouvrez aussi sur le firewall du serveur :

Protocole	Port par défaut	Variable de surcharge
TCP	7881	LIVEKIT_RTC_TCP_PORT
UDP	7882	LIVEKIT_RTC_UDP_PORT

Le template utilise le mode UDP multiplexé sur un port unique plutôt que la plage LiveKit historique. Si vous déployez deux stacks Cenaclo sur le même serveur, donnez à la seconde une autre paire de ports via les deux variables ci-dessus.

3. Secrets et variables

Le premier déploiement ne demande aucun collage manuel dans l’écran Environment Variables.

• Les variables SERVICE_PASSWORD_*, SERVICE_PASSWORD_64_* et SERVICE_URL_* sont générées par Coolify et réutilisées par les services.
• JWT_PRIVATE_KEY, JWT_PUBLIC_KEY, VAPID_PUBLIC_KEY, VAPID_PRIVATE_KEY, AUTH_IP_SALT, EMAIL_HASH_PEPPER, STORAGE_LOCAL_SIGNING_SECRET et CENACLO_MASTER_KEY_SECRET sont générés au premier démarrage du backend, puis persistés dans un volume propre à la ressource.
• LISTMONK_SEED_SMTP_MODE vaut skip par défaut pour que le premier déploiement soit autonome. Vous configurerez le SMTP plus tard, dans l’interface Listmonk ou via les variables LISTMONK_SMTP_*. Voir Configurer les emails.
• infra/coolify/.env.coolify.example ne liste que des surcharges avancées et des variables de migration. Ce n’est pas un fichier à recopier.
• Le replay vidéo fonctionne sans réglage : le conteneur Egress charge la page de composition sur le service web interne et rejoint LiveKit par ws://livekit:7880, hôte déjà déclaré dans CENACLO_LIVE_EGRESS_ALLOWED_HOSTS. Si vous branchez un LiveKit externe, surchargez les deux ensemble : une liste qui ne contient pas l’hôte réellement joint par l’Egress fait refuser la page, donc aucun replay.

Ne collez jamais un secret réel dans un fichier versionné du dépôt.

4. Déployer

1. Cliquez sur Deploy.
2. Attendez que les huit services permanents passent à l’état sain : postgres, redis, seaweedfs, livekit, livekit-egress, listmonk, backend et web.
3. Vérifiez que les trois exécutions ponctuelles se terminent bien : listmonk-db-init, listmonk-seed et livekit-egress-config sont des jobs one-shot qui doivent atteindre le statut completed.
4. Ouvrez https://app.example.com/install.

Le backend applique ses migrations de schéma pendant son démarrage. Aucune commande de migration n’est à lancer manuellement.

5. Terminer le wizard d’installation

Le wizard /install est de la logique applicative Cenaclo : il est identique quel que soit le mode de déploiement. Il comporte six étapes.

Capture prise sur un déploiement Coolify réel : les six étapes sont affichées en haut et la première arrive avec le domaine backend déjà rempli. Le domaine visible sur cette capture est celui de l’instance ayant servi à la validation ; le vôtre sera celui que vous avez assigné à la section précédente.

1. Domaine — vérifiez que le domaine backend proposé correspond bien à celui assigné dans Coolify. Il est prérempli depuis SERVICE_FQDN_BACKEND.
2. Compte administrateur — email et mot de passe du premier administrateur.
3. Passphrase de chiffrement — voir l’avertissement ci-dessous.
4. Double authentification TOTP — obligatoire pour l’administrateur avant l’accès complet.
5. Communauté — nom de la première communauté.
6. Branding — logo et couleur primaire.

La passphrase de chiffrement n’est jamais sauvegardée

La passphrase saisie à l’étape 3 dérive la master key qui chiffre en base les secrets sensibles (jetons de bots, secrets de webhooks, clés d’API média). Elle est distincte du mot de passe administrateur et Cenaclo ne la conserve nulle part. Notez-la dans un gestionnaire de mots de passe hors du serveur : sans elle, le chiffrement au repos devient illisible.

Cette passphrase de master key est également distincte de la passphrase de sauvegarde décrite à la section suivante. Ne confondez pas les deux.

6. Planifier les sauvegardes

Coolify génère automatiquement SERVICE_PASSWORD_64_BACKUP au premier déploiement et l’injecte comme CENACLO_BACKUP_PASSPHRASE. Révélez cette valeur dans la configuration du service, conservez-la dans un gestionnaire de mots de passe hors du serveur, puis créez une tâche planifiée Coolify sur le service backend :

/usr/local/bin/cenaclo-backup.sh --output-dir /var/backups/cenaclo

Fréquence recommandée : tous les jours à 02:15, heure serveur. Le script transmet la passphrase à age par descripteur de fichier et ne l’écrit pas dans les journaux.

Pour une communauté dont les replays vidéo sont déjà synchronisés par un autre mécanisme, utilisez l’archive légère :

/usr/local/bin/cenaclo-backup.sh --output-dir /var/backups/cenaclo --no-storage

Pour envoyer l’archive hors du serveur, renseignez CENACLO_BACKUP_RCLONE_REMOTE dans les secrets Coolify, par exemple cenaclo_backup_offsite:cenaclo-backups/prod, puis les variables RCLONE_CONFIG_CENACLO_BACKUP_OFFSITE_* de votre fournisseur S3, et gardez la commande standard. Les stratégies de rétention et de synchronisation objet sont détaillées dans Sauvegardes self-hosting, la restauration dans Restaurer une instance.

Purge de rétention

Ajoutez une seconde tâche planifiée quotidienne sur le service backend, après la sauvegarde :

/usr/local/bin/cenaclo-purge.sh --direct

Fréquence recommandée : tous les jours à 03:15, heure serveur. La purge applique les durées de rétention configurées et trace chaque exécution dans le journal d’audit.

7. Opérations courantes depuis Coolify

Ouvrez un terminal Coolify sur le service backend pour les opérations ponctuelles.

Export RGPD d’un utilisateur, par email ou par identifiant :

/usr/local/bin/cenaclo-export-user.sh --direct --user-email [email protected] --output /tmp/export.zip

/usr/local/bin/cenaclo-export-user.sh --direct --user-id USER_ID --output /tmp/export.zip

L’archive ZIP contient user.json, messages.json, attachments/ et audit_log.json. Copiez-la hors du conteneur, puis supprimez-la.

La récupération d’un accès administrateur perdu suit une procédure dédiée : voir Récupération administrateur.

8. Mettre à jour et revenir en arrière

Deux parcours sont supportés :

• modifier CENACLO_VERSION vers un tag d’image publié, puis cliquer Deploy ;
• cliquer Redeploy pour reprendre le tag courant et recréer les conteneurs.

Après le déploiement, contrôlez les deux sondes de santé :

curl -I https://api.example.com/healthz
curl -I https://app.example.com/healthz

En cas d’échec de migration ou de sonde de santé, Coolify conserve l’état de la ressource et affiche les journaux du service fautif.

Pour revenir en arrière, sélectionnez le dernier déploiement sain dans l’historique de la ressource et cliquez Rollback. Le rollback natif rejoue la révision précédente avec les mêmes secrets et les mêmes volumes.

cenaclo-update.sh ne s’utilise pas sur une ressource Coolify

Le script infra/ops/cenaclo-update.sh est le wrapper du parcours Docker Compose. Sur une ressource Coolify, c’est Coolify qui déclenche et orchestre le redéploiement. Ne repointez pas non plus les tags d’images à la main sur les conteneurs. Détail des deux parcours dans Mettre à jour.

Si une migration destructive est en cause, restaurez d’abord une sauvegarde avant de redéployer : voir Restaurer une instance.

Limites connues

• Coturn n’est pas activé dans le template Coolify. Le relay TURN mutualisé est le chemin recommandé pour le live auto-hébergé. Un Coturn local reste possible en mode expert via le parcours Compose : voir Firewall self-hosting.
• Les certificats TLS publics, les domaines Coolify et les tâches planifiées exigent une instance Coolify réelle. Ils ne peuvent pas être validés sur une maquette locale.
• Les archives produites restent dans le volume Docker backups de la ressource tant qu’un envoi rclone externe n’est pas configuré. Une panne de serveur emporterait alors les sauvegardes avec l’instance.

En cas de problème au déploiement, la page Dépannage recense les pannes les plus fréquentes des deux parcours.