Mettre à jour

Les deux parcours de déploiement se mettent à jour différemment, et il ne faut pas les mélanger.

Parcours	Ce qui déclenche la mise à jour	Retour arrière
Coolify	Changement de `CENACLO_VERSION` puis Deploy, ou webhook	Bouton Rollback natif
Docker Compose	Changement de version dans le dépôt de déploiement puis `cenaclo-update.sh`	Manuel, en repointant le dépôt

Dans les deux cas, le backend applique lui-même ses migrations de schéma pendant son démarrage. Il n’y a aucune commande de migration à lancer à la main, et aucun des deux parcours n’en propose.

Avant de commencer

Prenez une sauvegarde fraîche et vérifiez qu’elle s’est terminée sans erreur. Voir Sauvegardes self-hosting.
Notez la version actuellement déployée : c’est elle que vous remettrez en place si la mise à jour échoue.
Lisez les notes de version pour repérer une migration destructive ou un changement de configuration attendu.

Parcours Coolify

Le modèle Coolify déploie des images publiées, dont le tag est piloté par la variable CENACLO_VERSION. Coolify est le seul orchestrateur du redéploiement : il tire les images, redémarre les conteneurs et attend leurs sondes de santé.

Ouvrez la configuration de la ressource, onglet Environment Variables.
Remplacez CENACLO_VERSION, la variable de tag du template Coolify, par le tag de la version visée.
Cliquez Deploy.

Le bouton Redeploy fait la même chose sans changer de version : il recrée les conteneurs sur le tag courant. C’est le geste utile après un changement de variable d’environnement, par exemple une configuration SMTP.

Un webhook Coolify configuré sur la ressource remplace le clic Deploy et exécute exactement le même parcours.

Contrôler le résultat

Attendez que les huit services permanents repassent à l’état sain — postgres, redis, seaweedfs, livekit, livekit-egress, listmonk, backend et web — et que les trois exécutions ponctuelles listmonk-db-init, listmonk-seed et livekit-egress-config se terminent. Puis :

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.

Revenir en arrière

Sélectionnez le dernier déploiement sain dans l’historique de la ressource et cliquez Rollback. La révision précédente est rejouée avec les mêmes secrets et les mêmes volumes.

Ne repointez pas les tags d’images à la main sur les conteneurs : vous sortiriez l’état réel de ce que Coolify croit déployé, et le rollback natif ne retrouverait plus ses repères.

Parcours Docker Compose

Les services backend et web sont construits depuis les sources du dépôt de déploiement. La version déployée est donc celle qui est actuellement extraite sur le disque, pas un tag passé en argument.

1. Placer le dépôt sur la version visée

Le script de mise à jour ne fait ni git fetch ni git checkout : c’est délibéré, pour que l’opérateur reste maître de la version construite.

git fetch --tags origin
git checkout --detach <tag-ou-commit-de-release>

2. Lancer le wrapper

bash infra/ops/cenaclo-update.sh \
  --compose-file infra/compose/docker-compose.yml \
  --env-file infra/compose/.env

Le script enchaîne quatre étapes, dans cet ordre :

docker compose pull — met à jour les images des services qui en déclarent une (Postgres, Redis, SeaweedFS, LiveKit, Listmonk…) ;
docker compose build --pull — reconstruit backend et web depuis les sources extraites, en rafraîchissant leurs images de base ;
docker compose up -d — recrée les services modifiés ;
l’attente de la sonde /healthz, interrogée depuis l’intérieur du conteneur backend parce que le Compose ne publie pas le port 3000 sur l’hôte.

Si la sonde n’est pas satisfaite dans le délai imparti, le script sort en erreur. Il ne tente aucun retour arrière automatique.

Options utiles

Option	Effet	Défaut
`--compose-file FICHIER`	Fichier Compose ciblé	`infra/compose/docker-compose.yml`
`--env-file FICHIER`	Fichier d’environnement Compose	aucun
`--health-url URL`	Sonde interrogée dans le conteneur backend	`http://127.0.0.1:3000/healthz`
`--timeout SECONDES`	Délai total d’attente de la sonde	`60`
`--interval SECONDES`	Délai entre deux tentatives	`2`

Ces options ont chacune un équivalent en variable d’environnement : COMPOSE_FILE, COMPOSE_ENV_FILE, CENACLO_HEALTH_URL, CENACLO_HEALTH_TIMEOUT_SECONDS, CENACLO_HEALTH_INTERVAL_SECONDS et CENACLO_HEALTH_REQUEST_TIMEOUT_SECONDS.

Sur une petite machine, la reconstruction des images peut dépasser le délai par défaut de la sonde. Augmentez --timeout plutôt que de relancer en boucle.

Revenir en arrière

Il n’y a pas de bouton : remettez le dépôt de déploiement sur la version connue comme saine, puis relancez le même wrapper.

git checkout --detach <tag-ou-commit-precedent>
bash infra/ops/cenaclo-update.sh \
  --compose-file infra/compose/docker-compose.yml \
  --env-file infra/compose/.env

Cette manœuvre remet le code en arrière. Elle ne défait pas une migration de schéma déjà appliquée. Si la nouvelle version a modifié la base de façon irréversible, le retour arrière passe par une restauration de sauvegarde : voir Restaurer une instance.

Ce qui est rejoué à chaque mise à jour

Les migrations de schéma, au démarrage du backend.
Le seed Listmonk, avant le démarrage du backend : l’utilisateur d’API est recréé avec un jeton neuf, les modèles d’emails sont remis à niveau, et la configuration SMTP est réappliquée si vous l’avez confiée aux variables. Voir Configurer les emails.

Les secrets générés au premier démarrage — clés JWT, clés de notifications push, secret de master key, sels applicatifs — ne sont pas régénérés : ils sont relus depuis leur volume dédié. Une mise à jour ne déconnecte donc pas vos membres et ne rend pas illisibles les données chiffrées au repos.

Après la mise à jour

Les deux sondes /healthz répondent.
La connexion d’un compte existant fonctionne.
Un message envoyé dans un salon arrive en temps réel.
Un email de test apparaît bien dans le journal des envois.

Si l’un de ces contrôles échoue, la page Dépannage recense les causes les plus fréquentes.