Mise à jour de Koha : passer à une version maintenue sans perdre de données

Le cycle des versions de Koha

La communauté Koha publie deux versions majeures par an, en mai et en novembre, autour du 22 du mois. La numérotation suit l'année et le mois : 25.05 est la version de mai 2025, 25.11 celle de novembre 2025. Entre deux versions majeures sortent chaque mois des versions de maintenance (25.11.03, par exemple), qui n'apportent que des corrections de bogues et des correctifs de sécurité.

Plusieurs branches sont maintenues en parallèle et désignées par leur ancienneté relative : stable pour la plus récente, oldstable pour la précédente, oldoldstable pour celle d'avant. Depuis la version 22.11, la version de novembre des années paires est en outre une LTS (Long Term Support), avec une maintenance prolongée d'environ trois ans et demi, pensée pour les établissements qui ont besoin de stabilité.

Voici l'état des branches en novembre 2026 :

La prochaine version majeure, la 26.11, est attendue autour du 22 novembre 2026 selon le calendrier de la communauté ; suivant la règle des années paires, elle devrait devenir la prochaine LTS. En règle générale, la communauté maintient deux à trois versions majeures à la fois, chacune pendant environ dix-huit mois en moyenne, hors LTS. Une instance qui n'a pas été touchée depuis trois ou quatre ans est donc déjà hors maintenance.

Les risques de rester sur une ancienne version

• Plus de correctifs de sécurité. Chaque version de maintenance corrige souvent des vulnérabilités réelles : injection SQL, cross-site scripting, exécution de code dans les modèles. Hors des branches maintenues, ces correctifs n'arrivent plus, alors que l'OPAC est un service public exposé à Internet qui contient des données personnelles de lecteurs.
• Des dépendances système périmées. Koha tourne sur Debian ou Ubuntu avec Perl et MariaDB ; si le système d'exploitation n'est plus maintenu lui non plus, le problème dépasse Koha.
• Des fonctions qui n'arrivent jamais. Modules entiers, améliorations d'accessibilité de l'OPAC, API REST : elles n'existent que dans les versions récentes.
• Un saut de plus en plus cher. Mettre à jour tous les six ou douze mois relève de la routine ; le faire après quatre ans devient un projet, avec tests, reprise des personnalisations et nouvelle formation.
• Moins de monde pour aider. Les listes de la communauté et les prestataires travaillent sur les versions en cours ; sur une version abandonnée, les réponses se font rares.

Ce qui change entre les versions majeures

Quelques jalons expliquent pourquoi le saut se remarque autant quand on traîne plusieurs années de retard. La liste n'est pas exhaustive, chaque version majeure apportant des centaines de corrections et des dizaines d'améliorations, mais elle permet d'anticiper ce qui changera à l'écran et dans l'exploitation.

De tous ces changements, celui qui génère le plus de travail lors d'une mise à jour est le passage à Bootstrap 5. Si votre OPAC a un CSS maison écrit pour les versions précédentes, des classes d'alignement et d'espacement ont changé de nom et ne s'appliqueront plus. Rien de grave, mais c'est un vrai travail, qui doit figurer dans le devis.

Mise à jour de Koha : la méthode pour sauter plusieurs versions

Koha ne saute pas directement d'une version très ancienne à l'actuelle sans passer par les intermédiaires : chaque version majeure a ajouté ses propres mises à jour de schéma, et toutes doivent s'appliquer dans l'ordre. La méthode éprouvée est la suivante :

1. Cloner la production sur un serveur de test : base de données complète, fichiers de configuration, modèles et CSS personnalisés.
2. Consigner le point de départ : version exacte de Koha, version du système d'exploitation et de MariaDB ou MySQL, moteur de recherche utilisé et liste des plugins installés.
3. Mettre à jour le système d'exploitation s'il n'est plus maintenu. Il est courant qu'un Koha vieux de quatre ans tourne sur une Debian qui ne reçoit plus de correctifs.
4. Monter branche par branche, en laissant Koha appliquer les mises à jour de schéma à chaque palier et en vérifiant que l'instance démarre avant de continuer.
5. Reconstruire les index de recherche une fois la version cible atteinte.
6. Revoir les personnalisations : CSS de l'OPAC, modèles modifiés, plugins, notifications et rapports SQL enregistrés.
7. Tester avec l'équipe de la bibliothèque les flux réels : cataloguer, prêter, rendre, réserver, renouveler, produire le rapport de fin de mois.
8. Programmer la fenêtre de production en dehors des heures d'ouverture, avec une sauvegarde immédiatement antérieure et un plan de retour arrière.

La mise à jour du schéma de base de données

C'est l'étape qui inquiète le plus et, paradoxalement, la plus automatisée. Au premier démarrage de la nouvelle version, Koha détecte la version enregistrée dans la base et exécute les mises à jour en attente, l'une après l'autre. Sur un gros catalogue, cela peut prendre de quelques minutes à plus d'une heure, car certaines mises à jour réécrivent des tables entières.

Trois précautions ne se négocient pas : faire un export complet de la base juste avant de commencer, vérifier qu'il reste assez d'espace disque pour la croissance temporaire des tables, et ne jamais interrompre le processus en cours de route. En cas d'échec, on restaure l'export et on recommence ; c'est pourquoi la répétition préalable sur un clone fait toute la différence entre un incident maîtrisé et une urgence.

Ce qui casse : plugins, modèles, CSS et rapports

Le cœur de Koha migre bien. Ce qui demande une revue, c'est tout ce qui a été construit par-dessus :

• Plugins : chacun déclare les versions de Koha avec lesquelles il est compatible. Un plugin non maintenu peut rester en route ; il faut alors décider de le remplacer, de l'adapter ou de l'abandonner.
• Modèles modifiés directement : si quelqu'un a édité les fichiers de modèles de l'OPAC sur le serveur, ces changements sont perdus à la mise à jour. La bonne pratique est de les réimplémenter avec les préférences de personnalisation prévues par Koha.
• CSS de l'OPAC : le point critique du passage à Bootstrap 5, avec les classes d'alignement, d'espacement et de flottement à revoir.
• Rapports SQL enregistrés : ils interrogent directement les tables. Si une version a modifié la structure d'une table, le rapport cesse de fonctionner ou, pire, renvoie des chiffres faux sans prévenir. Il faut les revalider un par un.
• Intégrations : authentification LDAP ou SAML, automates de prêt en SIP2, moissonnage OAI-PMH et tout usage de l'API REST doivent être testés explicitement.
• Notifications et modèles de courriel : les avis de retard et de réservation disponible peuvent demander des ajustements si les variables disponibles ont changé.

Former les équipes après le saut

Si l'instance date d'avant la refonte de l'interface professionnelle, l'équipe découvrira un système différent le lundi matin. La logique du catalogage et de la circulation ne change pas, mais la navigation, les menus et l'emplacement de plusieurs actions, si. Dans les projets de mise à jour de BiblioLabTech, cela se règle avec une ou deux sessions courtes par domaine (catalogage, circulation, acquisitions), appuyées sur un guide interne illustré de captures d'écran du système déjà mis à jour, et non du manuel générique.

Prévoyez aussi un support renforcé pendant les deux premières semaines. La plupart des demandes de cette période ne sont pas des pannes, mais des questions du type « où est passée cette option ? ».

La check-list avant la mise à jour

• Export complet de la base de données, vérifié et restauré au moins une fois dans l'environnement de test.
• Copie des fichiers de configuration, des modèles et du CSS personnalisé.
• Inventaire des plugins, avec leur version et leur compatibilité déclarée.
• Liste des rapports SQL enregistrés à revalider.
• Version cible arrêtée : stable récente ou LTS, selon la tolérance au changement de l'établissement.
• Fenêtre de maintenance convenue avec la bibliothèque, hors période d'examens ou d'inscriptions.
• Plan de retour arrière écrit : dans quelles conditions on abandonne, et combien de temps prend la restauration.
• Un responsable chargé d'annoncer aux usagers l'indisponibilité de l'OPAC pendant la fenêtre.

Si votre instance n'a pas été mise à jour depuis des années et tourne sur un serveur que personne n'entretient, la mise à jour est le bon moment pour repenser l'infrastructure : voir notre guide de l'hébergement Koha. Si le catalogue traîne aussi des doublons et des notices sans exemplaire, combinez la mise à jour avec un nettoyage, comme décrit dans notre guide de la migration vers Koha. Pour ne pas revivre ce rattrapage, un support Koha applique les versions au fil de l'eau. Et si vous préférez confier l'opération, le service Koha de BiblioLabTech prend en charge les mises à jour de bout en bout ; c'est aussi l'occasion d'adopter BiblioScan AI, le catalogage MARC21 assisté par IA inclus sans surcoût dans tout projet Koha de BiblioLabTech.