Mettre à jour son instance¶
Vous hébergez votre propre instance de Kirexo et vous voulez passer à une version plus récente sans perdre de données.
Prérequis : une instance installée en suivant Installer Kirexo chez soi. Toutes les commandes se lancent depuis le répertoire d'installation, /opt/kirexo si vous avez suivi le tutoriel.
Principe¶
La version est épinglée par la ligne KIREXO_VERSION de .env. Aucune mise à jour ne se produit sans que vous modifiiez cette ligne, et un docker compose pull seul ne change rien. Le nom latest existe côté registre d'images, mais il n'est ni utilisé ni recommandé.
Kirexo suit le versionnement sémantique : MAJEUR.MINEUR.CORRECTIF. Tant que la version majeure vaut 0, une version mineure peut contenir un changement incompatible : lisez les notes de chaque version intermédiaire avant de sauter plusieurs versions.
Au démarrage d'une nouvelle version, Kirexo applique ses migrations, c'est-à-dire les modifications de la structure de la base de données qu'elle exige. Elles ne se défont pas : la sauvegarde prise juste avant est le seul moyen de revenir en arrière.
Mettre à jour¶
Dans la suite, X.Y.Z désigne la version visée, telle qu'affichée sur la page des versions. Suivez les étapes dans cet ordre, sans en sauter une.
-
Lisez les notes de version de
X.Y.Zsurhttps://gitlab.com/shaurifr/kirexo/-/releases, ainsi que celles de toutes les versions intermédiaires. -
Sauvegardez, en suivant Sauvegarder. Les migrations s'appliquent automatiquement au démarrage : la sauvegarde d'avant est la seule fenêtre où l'état antérieur reste récupérable.
-
Récupérez les fichiers de la version visée, par l'adresse de la version, pas par le lien
latest:curl -fsSLO https://gitlab.com/shaurifr/kirexo/-/releases/X.Y.Z/downloads/compose.yaml curl -fsSLO https://gitlab.com/shaurifr/kirexo/-/releases/X.Y.Z/downloads/.env.examplecompose.yamlse remplace toujours : il n'est pas fait pour être modifié, tout passe par.env. Votre.envn'est pas touché : seul le modèle.env.exampleest remplacé.Comparez ensuite les noms des variables du nouveau modèle à ceux de votre
.env. La commande n'affiche que les noms, jamais les valeurs : vos secrets ne s'affichent pas à l'écran.diff <(grep -oE '^#?[A-Z][A-Z0-9_]*=' .env.example | sed 's/^#//' | sort -u) <(grep -oE '^#?[A-Z][A-Z0-9_]*=' .env | sed 's/^#//' | sort -u)La commande compte une variable de la même façon, qu'elle soit en commentaire ou non : une ligne que vous avez décommentée dans
.envne produit pas d'alerte. Résultat attendu : aucune sortie si les noms concordent. Sinon, chaque ligne qui commence par<est une variable nouvelle du modèle, à reporter à la main dans.env; chaque ligne qui commence par>est une variable que le nouveau modèle n'a plus. Le rôle de chaque variable est décrit dans Paramètres de l'instance. -
Remplacez la valeur de
KIREXO_VERSIONparX.Y.Zdans.env. C'est le geste explicite de mise à jour. -
Arrêtez le worker, systématiquement, avant de télécharger les images. Le worker est le service qui exécute les tâches en arrière-plan :
Sans cet arrêt, l'ancien worker continuerait de traiter des tâches pendant que l'application modifie la structure de la base. L'arrêt est propre : la tâche en cours se termine.
-
Téléchargez les images de la nouvelle version :
Résultat attendu : Docker télécharge les images, sans erreur.
manifest unknownsignifie queKIREXO_VERSIONne désigne aucune version publiée : vérifiez-la sur la page des versions. -
Redémarrez :
L'application applique les migrations avant d'accepter des visites. Le worker ne redémarre qu'une fois l'application en bonne santé.
-
Vérifiez :
Résultat attendu :
(healthy)pourphp,Uppourworker, et un diagnostic qui se termine par[OK] Installation opérationnelle.Connectez-vous ensuite.
Si le redémarrage n'aboutit pas¶
Deux cas possibles après l'étape 7. unhealthy est l'état d'un service démarré qui ne répond pas correctement à ses contrôles de santé.
- « dependency failed » pour
worker:phpa dépassé le délai de démarrage toléré (environ cinq minutes) et apparaîtunhealthydansdocker compose ps, mais une migration longue peut être encore en cours. Lisezdocker compose logs php: tant que la dernière ligne[kirexo]est « application des migrations Doctrine... », sans ligne[kirexo] ERREUR, la migration continue. Attendez en suivantdocker compose logs -f php(Ctrl+Cpour en sortir) ; dès que « Migrations Doctrine à jour. » s'affiche, relancezdocker compose up -d: le worker démarre. phpunhealthyavec une ligne[kirexo] ERREURdans les journaux : lisezdocker compose logs php. Le conteneur ne redémarre pas en boucle. Si l'erreur porte sur les migrations, passez au retour arrière.
Retour arrière¶
Le retour arrière est une restauration complète, en suivant Restaurer, avec le compose.yaml de l'ancienne version (retéléchargé par l'adresse de sa version), le .env sauvegardé et la sauvegarde de la base prise avant la mise à jour.
- Revenir à une image antérieure ne défait pas les migrations déjà appliquées.
- Le passage à une version inférieure sans restaurer la sauvegarde n'est pas pris en charge.
Éviter les mises à jour automatiques¶
Un outil de mise à jour automatique des conteneurs, comme Watchtower, qui suit latest appliquerait une nouvelle version, changement incompatible compris, sans sauvegarde préalable ni arrêt du worker. C'est déconseillé : gardez la main sur KIREXO_VERSION.
Aucune notification de nouvelle version n'est intégrée à l'application : suivez la page des versions, https://gitlab.com/shaurifr/kirexo/-/releases.
Vérifier l'authenticité des images (facultatif)¶
Cette vérification est optionnelle : l'outil cosign n'est pas un prérequis de l'installation. Elle confirme que l'image de la version visée a bien été produite par le projet Kirexo.
Les images des versions publiées sont signées sans clé (sigstore) par la chaîne de publication du projet. Pour vérifier la version visée X.Y.Z :
cosign verify registry.gitlab.com/shaurifr/kirexo/kirexo-prod:X.Y.Z \
--certificate-identity-regexp='^https://gitlab\.com/shaurifr/kirexo' \
--certificate-oidc-issuer='https://gitlab.com'
- Succès : la commande affiche la liste JSON des signatures.
- Échec (
no matching signatures,certificate identity does not match) : ne déployez pas cette image.
Chaque version publie aussi l'inventaire des logiciels qu'elle contient (SBOM aux formats SPDX et CycloneDX, un jeu par architecture), téléchargeable depuis sa page.
Voir aussi¶
- Sauvegarder et restaurer son instance
- Paramètres de l'instance —
KIREXO_VERSIONet ce qui casse.