Montées de version

Les montées de version sur une instance Tale auto-hébergée passent par deux commandes : tale update bouge le binaire CLI à la nouvelle version et synchronise tes fichiers projet pour correspondre, puis tale deploy roule les conteneurs plateforme. Le déploiement utilise un pattern blue-green — la nouvelle couleur démarre à côté de l'ancienne, les healthchecks passent, le trafic bascule, l'ancienne couleur draine. Zéro downtime est le défaut ; si une release patch se comporte mal, tale rollback ramène le patch précédent en une commande, et tout ce qui est plus gros se récupère depuis le snapshot pré-upgrade.

Ce que tu ne fais plus, c'est garder la CLI synchronisée à la main : la CLI s'aligne elle-même sur l'instance automatiquement (voir plus bas), donc le seul pas délibéré est de choisir quand bouger de version avec tale update.

L'installation de la CLI vit dans Installer la CLI tale. Cette page couvre ce que fait chaque commande et comment le modèle de versions fonctionne.

La CLI suit l'instance automatiquement

Le binaire CLI est toujours à la même version que l'instance qu'il gère. Le workspace enregistre cette version dans tale.json ; à chaque commande, la CLI compare sa propre version à celle-là et, si elles diffèrent, se met à jour pour correspondre (en montant ou en descendant) avant de tourner. Quand elles correspondent déjà — le cas largement le plus fréquent — c'est un no-op sans appel réseau, donc tu ne le remarques jamais.

Cela veut dire que tu lances rarement tale update, sauf quand tu veux délibérément bouger vers une nouvelle version. Un coéquipier qui a installé une CLI plus récente que ton instance, ou restauré un snapshot plus ancien, obtient la bonne version de CLI automatiquement à sa prochaine commande. Il n'y a aucun flag pour désactiver ça — garder l'outil et l'instance au pas l'un de l'autre est ce qui rend les déploiements sûrs.

Avant de monter de version

Deux choses valent la peine d'être confirmées d'abord :

• Ta copie hors-hôte du volume backups est à jour — voir Backups et restauration. tale update snapshotte automatiquement les volumes de données avant toute étape qui peut migrer des données, mais le snapshot vit sur le même hôte ; la copie hors-hôte est ce qui survit à un disque mort.
• Les notes de version pour la version cible ne nomment pas un changement breaking. Les notes sont liées depuis la page de release GitHub ; les changements breaking sont flaggés comme tels en haut.

Si la montée de version traverse une version majeure (1.x → 2.x), lis les notes de migration de bout en bout avant de commencer. Les versions majeures sont où atterrissent les migrations de schéma et les changements de format de fichier de config.

Les deux commandes

tale update met à jour le binaire CLI, puis synchronise tes fichiers projet sur les templates de cette version. Il ne touche pas aux conteneurs en marche — c'est le boulot de tale deploy. Si la synchro des fichiers échoue, la CLI fait reculer son propre binaire à la version sur laquelle ton workspace était, pour que le binaire et tale.json ne dérivent jamais l'un de l'autre.

# Bouge la CLI et les fichiers projet à la dernière release
tale update

# Fixe une version précise (autorise les downgrades — voir Rollback)
tale update --version 0.10.2

# Aperçu du changement de version et de la synchro des fichiers sans rien toucher
tale update --dry-run

tale deploy fait le vrai redémarrage rolling, et il déploie toujours la version propre à la CLI — qui, grâce à l'alignement, est la version qu'enregistre ton workspace. Il trie les services en trois étages :

• Étage app — platform — roule à chaque déploiement, sans downtime (blue-green : la nouvelle couleur démarre à côté de l'ancienne, les healthchecks passent, le trafic bascule, l'ancienne couleur draine).
• Backend et compute — convex, sandbox, sandbox-egress — roulent à chaque déploiement eux aussi, pour ne jamais dériver en version d'avec platform. Chacun est un conteneur unique qui se recrée en place quand son image a réellement changé ; le déploiement draine d'abord le travail en cours (générations de chat pour convex, runs d'agent pour sandbox) pour que le bref redémarrage ne coupe pas une requête en vol.
• Étage à arrêt requis — db, proxy — laissés en marche et intacts par défaut (recréer Postgres ou le proxy est une brève coupure que tu ne veux pas sur un roll de routine). Passe --stop pour les mettre à jour ; le déploiement prévient et les nomme quand il les saute.

# Après tale update, roule les conteneurs pour correspondre (étage app + convex)
tale deploy

# Mets aussi à jour db/proxy (brève coupure pendant qu'ils se recréent)
tale deploy --stop

# Roule seulement des services spécifiques
tale deploy --services platform

# Aperçu sans changement
tale deploy --dry-run

--dry-run mérite d'être lancé avant chaque montée de version en production — il fait remonter les images manquantes, les migrations manquantes et les mismatches de dépendances sans toucher aux conteneurs en marche.

Le pattern blue-green

Une instance en marche est l'une des deux couleurs (blue ou green) à un instant donné. La phase de déploiement monte l'autre couleur, attend qu'elle passe les healthchecks, puis bascule l'upstream de Caddy sur la nouvelle couleur. L'ancienne couleur draine ses requêtes en vol (défaut 30 s), puis sort.

Trois garanties que le pattern te donne :

• Aucune fenêtre où les deux couleurs servent du trafic. Un constraint de base impose single-active — Caddy route vers la saine.
• Le rollback de patch est une commande. tale rollback redéploie la release patch précédente sur la couleur inactive et rebascule le trafic. Il refuse les downgrades minor et major — ceux-là peuvent laisser la base en avance sur le binaire, et leur chemin de récupération est une restauration de snapshot.
• Les healthchecks échoués bloquent la bascule. Si la nouvelle couleur ne passe pas dans le timeout, le déploiement abandonne et l'ancienne couleur continue à servir.

La procédure complète de déploiement, y compris la phase de cleanup, vit dans tale --help ; la recette côté opérateur est tale update && tale deploy && tale status et confirmation visuelle dans le navigateur.

Travailler avec les migrations de données

Chaque déploiement applique automatiquement les migrations de données en attente — mais seulement celles qui ne détruisent rien. Les migrations qui suppriment ou écrasent des données (suppression d'une table, retrait d'une colonne) ne tournent jamais sans surveillance : le déploiement les saute, affiche celles qui attendent et vous laisse la décision.

# Ce qui est appliqué, en attente, en échec
tale migrate status

# Appliquer les migrations en attente, en validant chaque étape destructrice
tale migrate up --step

# Tout appliquer sans confirmation (CI / après revue du plan)
tale migrate up --yes

# Ramener les données à une version antérieure
tale migrate down --to 0.3.3

Les migrations destructrices sauvegardent les lignes ou fichiers de configuration concernés avant d'y toucher : tale migrate down peut ainsi reconstruire ce qu'elles ont retiré. Les deux sens sont reprenables : la progression est suivie par migration (et par organisation pour les migrations de fichiers de configuration), un crash ou un timeout reprend donc là où il s'était arrêté.

Si une migration échoue pendant un déploiement, la plateforme démarre quand même sur son schéma actuel — le journal de démarrage affiche une erreur bien visible et tale migrate status montre la migration en échec avec son message. Corrigez la cause, puis relancez tale migrate up ; le travail déjà accompli est sauté.

Rollback

# Retour à la version patch précédente (demande confirmation)
tale rollback

# Ignorer l'invite en mode non-interactif
tale rollback --yes

tale rollback est limité aux pas de patch : il ne cible que la version précédente enregistrée, et refuse si cette version ne partage pas major.minor avec la plateforme qui tourne. Les releases patch ne portent jamais de migrations, donc redéployer le patch précédent est toujours sûr. Tout ce qui est plus gros peut avoir migré les données vers l'avant — déployer un binaire plus vieux sur des données migrées corrompt l'instance au lieu de la sauver. Pour ces cas, le chemin de récupération est de restaurer le snapshot pré-upgrade et de revenir à la version qui lui correspond avec tale update --version <version> suivi de tale deploy --stop (pour que db/proxy reculent aussi) ; le message de refus imprime les commandes exactes, et le walk complet vit dans Backups et restauration.

Comme le rollback démolit les conteneurs en cours d'exécution, la commande prévient de ce qu'elle s'apprête à faire et demande confirmation avant de tirer la moindre image ; passe --yes pour ignorer cette invite dans les scripts ou en CI.

Compatibilité de versions

Les versions Tale sont en semver. Les règles de compatibilité :

• Patch (0.9.0 → 0.9.1) — pas de migrations, pas de changements de config, tale rollback est toujours sûr.
• Minor (0.9.x → 0.10.x) — peut inclure des migrations forward-only ; tale rollback refuse, la récupération est restauration-de-snapshot plus redéploiement.
• Major (0.x → 1.x) — lis les notes de migration, planifie la fenêtre de maintenance, attends-toi à des surprises.

Sauter des versions mineures (passer de 0.9 à 0.11) est supporté tant que les migrations intermédiaires sont encore dans le binaire ; les notes de version le mentionnent quand ce n'est pas le cas.

Pour descendre délibérément d'une version — disons qu'une release minor se comporte mal et que tu as déjà inversé ses migrations — fixe la cible avec tale update --version <version>. La commande prévient quand la cible est plus ancienne que la version qui tourne et te rappelle d'inverser d'abord les migrations de données.

Monter depuis la 0.3.1 ou antérieure

Les instances en version 0.3.1 ou antérieure gardent les données du backend Convex dans le volume Docker platform-data. Les versions plus récentes font tourner Convex comme service à part entière avec son propre volume convex-data — et la copie automatique que les premières releases embarquaient pour ce déménagement n'est plus dans la CLI. Franchis cette frontière d'un coup et tale deploy pré-crée un volume convex-data vide : l'instance démarre vierge alors que chaque octet de tes données reste, intact, dans l'ancien volume platform-data. Rien n'est supprimé — mais les données ne bougent pas toutes seules, et tale update avertit quand il détecte cette situation.

Docker n'a pas de renommage natif de volume ; le déménagement passe donc par une copie via un conteneur intermédiaire. Exécute-la avant tale deploy, stack arrêtée, pour que rien ne garde le volume ouvert :

# 1. Repérer le volume legacy — <project> est l'`id` de tale.json.
docker volume ls | grep platform-data
# Les installations antérieures à la 0.2.33 utilisaient le préfixe
# fixe `tale_` au lieu de `<project>_` ; la destination ci-dessous
# garde `<project>_`.

# 2. Arrêter la stack.
docker compose -p <project> down

# 3. Créer le volume de destination et copier les données.
docker volume create <project>_convex-data
docker run --rm \
  -v <project>_platform-data:/from:ro \
  -v <project>_convex-data:/to \
  alpine sh -c "cd /from && cp -a . /to"

# 4. Rouler la stack, puis vérifier que tes données sont là.
tale deploy

# 5. Une fois vérifié seulement, récupérer l'espace de l'ancien volume.
docker volume rm <project>_platform-data

Un workspace de dev suit le même déménagement sous le scope -dev : <project>-dev_platform-data → <project>-dev_convex-data, avec docker compose -p <project>-dev down comme étape d'arrêt.

Si tu as déjà déployé et obtenu une instance vide, tes données sont toujours en sécurité dans platform-data. Arrête la stack, supprime le volume vide fraîchement créé avec docker volume rm <project>_convex-data, puis exécute la copie ci-dessus et redéploie.

Où cela s'inscrit

Le flow de montée de version noue chaque autre page d'exploitation — les backups sont ce qui rend une montée de version échouée récupérable, l'observabilité est ce qui te dit que la nouvelle couleur est saine, le durcissement est ce que tu reparcours après une version majeure. Si tu mets en place la CLI pour la première fois, Installer la CLI tale couvre le setup côté workstation ; si tu prends le pager en plein rollout, Dépannage nomme les symptômes.