Mise à niveau
Chaque version de NomaUBL est livrée sous la forme d'un nouveau nomaubl.jar. Une seule commande — nomaubl.sh upgrade <env> sous Linux/macOS ou nomaubl.cmd upgrade <env> sous Windows — fait passer un environnement installé de la version qu'il exécute actuellement à celle du JAR en place. Elle arrête le service, lance le volet -upgrade côté Java (migrations de schéma, fusion des données de référence, rafraîchissement des XSL du socle, fusion des XSL par document) puis redémarre le service. Un rapport complet est déposé sous ${appHome}/upgrade-reports/ et une sauvegarde de retour arrière sous ${appHome}/backup/<timestamp>/.
La même commande s'exécute sur toutes les plateformes prises en charge — il n'existe aucun parcours de mise à niveau réservé à Linux ou réservé à Windows. Il convient de choisir le wrapper correspondant à l'hôte.
Deux façons d'invoquer la commande
# Option A — le JAR est déjà en place
./nomaubl.sh upgrade prod
# Option B — laisser le wrapper remplacer le JAR au préalable
./nomaubl.sh upgrade prod /tmp/nomaubl-2026.06.0.jar
REM Option A — le JAR est déjà en place
nomaubl.cmd upgrade prod
REM Option B — laisser le wrapper remplacer le JAR au préalable
nomaubl.cmd upgrade prod C:\downloads\nomaubl-2026.06.0.jar
| Argument | Description |
|---|---|
env | Nom de l'environnement — le même que celui utilisé par start, stop, etc. Le wrapper résout la configuration depuis <env>/config/config.json. |
new_jar (facultatif) | Chemin vers le JAR cible. Le wrapper le copie par-dessus le nomaubl.jar existant (Linux) ou nomaubl-fat.jar (Windows) avant d'exécuter la mise à niveau. À omettre si le JAR a déjà été remplacé à la main. |
Les deux formes produisent le même état final. La seconde est utile quand une seule commande doit tout faire ; la première convient quand le pipeline de livraison dépose déjà le nouveau JAR en place.
En un coup d'œil — ce que fait la mise à niveau
La référence détaillée par étape (ce que -upgrade fait en interne, ce qui est préservé, ce qui est rafraîchi) se trouve sur la page Ligne de commande → upgrade.
Avant la mise à niveau
| Vérification | Raison |
|---|---|
Le nouveau JAR est bien celui attendu — java -jar nomaubl.jar -help affiche la version en tête. | Permet de détecter un build erroné posé à côté du wrapper. |
| L'utilisateur du service peut écrire dans le répertoire d'environnement et son parent. | La mise à niveau réécrit template/, xslt/, .versions/ et crée une sauvegarde. Un système de fichiers en lecture seule bloque la mise à niveau dès l'étape 1. |
| Le compte de base de données dispose des mêmes droits DDL qu'à l'installation (création de tables, d'index, de séquences, de vues). | L'étape 2 applique les deltas de schéma — les droits DDL sont requis même pour une exécution idempotente sur la même version. |
Une véritable sauvegarde de base de données est en place (pas seulement l'instantané backup/ par environnement). | Le répertoire backup/ conserve une copie des fichiers sur disque ; il ne réalise pas d'instantané de la base. Il convient de prendre la sauvegarde habituelle de la base avant une version majeure. |
| Une fenêtre de maintenance suffisante pour un redémarrage — typiquement 1 à 5 minutes par environnement. | Le service est indisponible de l'étape 1 jusqu'à l'étape 6. |
Aucun mode « maintenance » particulier n'est requis pour NomaUBL au-delà de l'arrêt du service — le wrapper s'en charge automatiquement.
Exécuter la mise à niveau
Linux / macOS
cd /opt/nomaubl
./nomaubl.sh upgrade prod
Sortie type :
[upgrade] env: prod
[upgrade] stopping service...
NomaUBL [prod] stopped
[upgrade] running -upgrade (this may take a minute)...
... (Java-side step log) ...
[upgrade] starting service...
Starting NomaUBL [prod] (port=8090)...
NomaUBL [prod] started (PID 12347)
URL: http://localhost:8090/
Log: /opt/nomaubl/nomaubl-prod.log
Windows
cd C:\nomaubl
nomaubl.cmd upgrade prod
Même sortie, même sémantique de code de sortie — 0 en cas de succès, non nul en cas d'échec.
Plusieurs environnements
La mise à niveau s'applique par environnement. Avec trois environnements sur le même hôte, la commande est lancée trois fois :
./nomaubl.sh upgrade demo
./nomaubl.sh upgrade uat
./nomaubl.sh upgrade prod
nomaubl.cmd upgrade demo
nomaubl.cmd upgrade uat
nomaubl.cmd upgrade prod
La promotion suit l'ordre dicté par le processus de livraison (typiquement demo → uat → prod). Chaque exécution utilise le même JAR — le JAR est partagé entre les environnements de l'hôte.
En cas d'échec
Le wrapper se termine avec un code non nul et laisse le service arrêté. Le message affiché est le suivant :
[upgrade] ⚠ FAILED — service left stopped.
[upgrade] Inspect the report under ${appHome}/upgrade-reports/ and
[upgrade] roll back from ${appHome}/backup/<latest>/ if needed.
Les deux fichiers à consulter :
| Fichier | Emplacement | Information fournie |
|---|---|---|
| Le rapport de mise à niveau | ${appHome}/upgrade-reports/upgrade-<timestamp>.md | Résultat par étape. L'en-tête du rapport indique le répertoire d'environnement résolu et l'URL JDBC, de sorte qu'une erreur d'hôte ou de chemin saute aux yeux. |
| L'instantané de sauvegarde | ${appHome}/backup/<timestamp>/ | Copie du répertoire d'environnement et de l'ancien JAR, prise avant la mise à niveau. Sert au retour arrière. |
Retour arrière
./nomaubl.sh stop prod # sécurité — généralement déjà arrêté
cp -r /opt/nomaubl/backup/<timestamp>/* /opt/nomaubl/prod/
cp /opt/nomaubl/backup/<timestamp>/nomaubl.jar /opt/nomaubl/ # restauration de l'ancien JAR
./nomaubl.sh start prod
nomaubl.cmd stop prod
xcopy /E /I /Y C:\nomaubl\backup\<timestamp>\* C:\nomaubl\prod\
copy /Y C:\nomaubl\backup\<timestamp>\nomaubl-fat.jar C:\nomaubl\nomaubl-fat.jar
nomaubl.cmd start prod
Après un retour arrière, il convient de prendre une nouvelle sauvegarde de base de données avant de retenter la mise à niveau — les deltas de schéma ont pu être partiellement appliqués avant l'échec.
Nouvelle tentative
Le volet -upgrade côté Java est idempotent : une nouvelle exécution sur le même environnement saute les étapes déjà réussies et reprend à celle qui a échoué. Une fois la cause sous-jacente corrigée (réseau, privilège manquant, etc.), il suffit de relancer :
./nomaubl.sh upgrade prod # ou nomaubl.cmd upgrade prod
Paramètres → Historique des mises à niveau
Chaque installation, mise à niveau et migration exécutée sur l'environnement est répertoriée sous Paramètres → Historique des mises à niveau. Un clic sur une ligne affiche le rapport complet dans le volet de droite — contenu identique au fichier sous ${appHome}/upgrade-reports/. La liste est en lecture seule ; rien ne peut être relancé depuis cette page.
C'est la piste d'audit destinée à l'exploitant — utile pour confirmer « oui, 2026.06.0 a bien été passée sur prod mardi dernier » sans se connecter en SSH à l'hôte.
Pièges courants lors d'une mise à niveau
| Erreur | Symptôme | Correction |
|---|---|---|
Exécution d'upgrade sur le mauvais environnement. | Le mauvais environnement tombe pendant une minute. | Lire la ligne [upgrade] env: <env> au démarrage ; annuler avec Ctrl+C si ce n'est pas celui prévu. |
| Le nouveau JAR est absent ou corrompu. | [upgrade] new JAR not found: <path> ou Error: Unable to access jarfile. | Vérifier que le fichier existe et a la taille attendue ; le retélécharger si besoin. |
| Le service a été démarré à la main, en dehors du wrapper. | Le wrapper ne voit aucun fichier PID → considère que le service n'est pas en cours → la mise à niveau se poursuit sans arrêter la JVM. Deux processus se disputent brièvement la base de données. | Toujours utiliser le wrapper pour démarrer ou arrêter le service. |
| Un delta de schéma échoue parce que l'utilisateur de la base a perdu ses droits DDL. | Le rapport consigne ORA-01031: insufficient privileges (Oracle) ou permission denied for schema (PostgreSQL). | Réaccorder CREATE TABLE, CREATE INDEX, CREATE SEQUENCE, CREATE VIEW ; relancer la mise à niveau. |
| Les XSL personnalisées contiennent des TAG obsolètes signalés. | Le rapport liste, par modèle, des entrées sous « removed TAGs ». | Ouvrir le .xsl du modèle et retirer les lignes <!-- removed in <version> --> une fois l'adaptation effectuée. |
| Disque saturé sur la partition de l'environnement. | L'étape de sauvegarde échoue. | Libérer de l'espace ; relancer. Le répertoire backup/ grossit au fil des instantanés conservés — il convient d'élaguer les anciens pour maîtriser l'occupation disque. |
Et ensuite
- Service et systemd — superviser le service mis à niveau.
- Gestion → Ligne de commande → upgrade — référence complète du volet
-upgradecôté Java. - Supervision → Service et journaux — confirmer que la mise à niveau s'est appliquée (
/api/build-infoaffiche la nouvelle version).