Aller au contenu

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.

  1. Lisez les notes de version de X.Y.Z sur https://gitlab.com/shaurifr/kirexo/-/releases, ainsi que celles de toutes les versions intermédiaires.

  2. 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.

  3. 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.example
    

    compose.yaml se remplace toujours : il n'est pas fait pour être modifié, tout passe par .env. Votre .env n'est pas touché : seul le modèle .env.example est 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 .env ne 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.

  4. Remplacez la valeur de KIREXO_VERSION par X.Y.Z dans .env. C'est le geste explicite de mise à jour.

  5. 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 :

    docker compose stop worker
    

    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.

  6. Téléchargez les images de la nouvelle version :

    docker compose pull
    

    Résultat attendu : Docker télécharge les images, sans erreur. manifest unknown signifie que KIREXO_VERSION ne désigne aucune version publiée : vérifiez-la sur la page des versions.

  7. Redémarrez :

    docker compose up -d --wait
    

    L'application applique les migrations avant d'accepter des visites. Le worker ne redémarre qu'une fois l'application en bonne santé.

  8. Vérifiez :

    docker compose ps
    docker compose exec php bin/console app:install:check
    

    Résultat attendu : (healthy) pour php, Up pour worker, 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 : php a dépassé le délai de démarrage toléré (environ cinq minutes) et apparaît unhealthy dans docker compose ps, mais une migration longue peut être encore en cours. Lisez docker compose logs php : tant que la dernière ligne [kirexo] est « application des migrations Doctrine... », sans ligne [kirexo] ERREUR, la migration continue. Attendez en suivant docker compose logs -f php (Ctrl+C pour en sortir) ; dès que « Migrations Doctrine à jour. » s'affiche, relancez docker compose up -d : le worker démarre.
  • php unhealthy avec une ligne [kirexo] ERREUR dans les journaux : lisez docker 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