14. Livrer

Votre module fonctionne chez vous. Voici comment il arrive ailleurs.

Empaqueter

kewos module pack ./modules/library --out library-0.3.0.kws

Un .kws est une archive, et vous pouvez l’ouvrir pour vérifier ce qu’elle contient. Elle porte en plus un manifeste d’empreintes : chaque fichier y est listé avec son empreinte, ce qui permet de détecter qu’un paquet a été modifié entre l’export et l’installation.

Installer

kewos module install library-0.3.0.kws --modules-root /opt/kewos/current/modules

Puis alignez le schéma et redémarrez :

kewos reconcile --confirm --modules-root /opt/kewos/current/modules
sudo systemctl restart kewos kewos-worker

Et n’oubliez pas d’activer le module pour l’installation, sans quoi il restera invisible (voir Le rendre visible).

La signature

Par défaut, install refuse un paquet non signé. Un module qui arrive d’un tiers doit prouver son origine : il s’exécute dans le processus du serveur, avec accès à la base.

En développement, cette exigence serait une friction inutile, alors le comportement suit l’environnement :

# On a developer machine: accepted without a signature.
KEWOS_ENV=development kewos module install library-0.3.0.kws

# On a server, you have to say so explicitly.
kewos module install library-0.3.0.kws --allow-unsigned
kewos module install library-0.3.0.kws --require-signed

Autoriser le non-signé ne désactive pas le contrôle d’intégrité

--allow-unsigned porte sur l’auteur, pas sur le contenu. Un paquet dont un fichier ne correspond plus à son empreinte reste refusé, signé ou non.

Autrement dit : vous pouvez renoncer à savoir qui l’a fabriqué ; vous ne pouvez pas renoncer à savoir qu’il est arrivé intact.

Pour signer, il faut une paire de clés et que l’installation cible connaisse votre clé publique. Adressez-vous à Kewos si vous distribuez des modules à vos clients.

Les migrations

Dès la deuxième version de votre module, une modification de schéma se livre en migration.

modules/library/migrations/versions/0001_add_lost_note.py

Jamais de migration ailleurs que dans migrations/

Pas dans un hook d’installation, pas dans un événement applicatif, pas dans register(). Une modification de données déclenchée par un événement s’exécute un nombre de fois que personne ne peut prédire.

Et les migrations sont non destructives par défaut : on renomme, on remplit, on ajoute. Une suppression de colonne ou une contrainte non nulle sans valeur de remplissage se demande explicitement, parce qu’elle peut détruire des données d’un client.

Une liste de contrôle avant de livrer

• Le manifeste porte la bonne version et la bonne catégorie.
• icon.svg existe et utilise currentColor.
• Chaque fichier de langue a les mêmes clés que les autres.
• Aucune chaîne visible n’est écrite en dur, ni en Python ni en JSON.
• Les groupes du module sont préfixés par son nom.
• Aucune machine à états écrite à la main.
• Aucun montant en flottant.
• Aucun import d’un autre module métier.
• Les tests passent, y compris un cas limite et un cas d’erreur par comportement.
• Un compte non administrateur a été testé, pas seulement kws_admin.

Et ensuite

Vous avez fait le tour. Deux compléments valent la lecture :

• Python ou YAML, si vous hésitez encore sur le format.
• Lire un document (OCR), pour transformer une image en texte.

Le module fini, à télécharger

Vous n’êtes pas obligé de tout retaper. Le module de ce parcours est empaqueté tel qu’il est décrit ici, avec ses écrans, ses traductions, ses droits, son état PDF, son flux et ses tests :

• library-0.3.0.kws (23 Ko) : le module de bibliothèque complet, des étapes 1 à 13, plus ses règles métier, son amende avec sa devise et sa carte des adhérents.

Empreinte, à vérifier avant d’installer quoi que ce soit :

03e62249c512b723c021a820131c8d4c7b83b7dc8b471217f0e2152d83fd6676  library-0.3.0.kws

sha256sum library-0.3.0.kws

L’installer sur votre instance

kewos module install library-0.3.0.kws \
  --database-url "$KEWOS_DATABASE_URL" \
  --modules-root "$KEWOS_MODULES_ROOT" \
  --allow-unsigned

installed library 0.1.0 (UNSIGNED) into /opt/kewos/app/modules

--modules-root doit exister. Sinon :

REFUSED: modules root /opt/kewos/modules does not exist (or is not a directory);
point --modules-root at the instance's modules folder

Le dossier n’est pas créé pour vous, volontairement : une faute de frappe déposerait le module dans un chemin que le serveur ne lit jamais, et l’installation annoncerait un succès.

Puis les deux gestes que le paquet ne fait pas à votre place :

# 1. The schema: the module's tables do not exist yet.
kewos reconcile --confirm

# 2. Restart, so the process loads the module it now has on disk.
systemctl restart kewos

Et activez-le pour l’installation, dans Réglages → Modules. C’est l’étape 4 du parcours, et c’est celle qu’on oublie : un module dont l’API répond parfaitement reste invisible tant qu’il n’est pas activé, sans erreur ni journal.

Pourquoi il refuse d’abord

kewos module install library-0.3.0.kws --database-url ... --modules-root ...

REFUSED: package is not signed; install it with an explicit allowance
(never in production) or publish a signed build

Ce paquet est non signé, et c’est volontaire : le signer voudrait dire vous faire installer sur votre instance quelque chose qui porte notre garantie, pour un module d’exercice. Le --allow-unsigned que vous tapez est un consentement, pas une formalité contournée — c’est exactement ce que vous ne taperez jamais sur une machine de production.

Un module que vous publiez pour de vrai se signe au moment de la publication, avec la clé de votre chaîne de livraison, jamais depuis le poste qui l’écrit.

Et après ?

Vous savez construire un module. L’autre moitié du métier est d’en étendre un qui existe déjà, sans le copier : Étendre un module existant.