mabibli_ynh/PUBLICATION.md

Mettre MaBibli en production, et la mettre à jour

Deux marches à suivre, éprouvées sur un serveur réel le 2026-08-18 : la première mise en production, puis la montée de version. Les contraintes qui les gouvernent sont expliquées dans A_FAIRE.md — ici, ce sont les gestes.

Principe qui explique toute la chaîne : le serveur ne compile jamais. Il télécharge une archive déjà produite, vérifie son empreinte, et la déploie. Le SDK .NET n'est nécessaire que sur la machine de développement.

machine de dev                    Gitea                        serveur YunoHost
──────────────                    ─────                        ────────────────
publier-release.sh
  → archive .tar.gz   ────────►  release du dépôt `mabibli`
  → manifest.toml     ────────►  dépôt `mabibli_ynh`  ──────►  yunohost app install
     (url + sha256)                                            (vérifie le sha256)

---

A. Première mise en production

A.1 Préalables, une seule fois

• Le dépôt du code (mabibli) est public sur Gitea. ynh_setup_source télécharge sans jeton ; sur un dépôt privé Gitea répond 404 — indiscernable d'une release absente.
• Le domaine dédié existe côté YunoHost. MaBibli s'installe sur un domaine entier (mabibli.mondomaine.tld), jamais sur un sous-chemin :

sudo yunohost domain add mabibli.mondomaine.tld

• Le SDK .NET est installé sur la machine de développement (dotnet --version).

A.2 Produire l'archive

Depuis mabibli_ynh, avec le dépôt du code à côté (../mabibli) :

./build/publier-release.sh

Le script compile en Release self-contained, vérifie le publish (binaire présent, wwwroot/ embarqué, toutes les ressources d'index.html réellement sur disque, aucun placeholder d'empreinte non substitué), produit l'archive de façon reproductible, en calcule le sha256, et réécrit version, amd64.url et amd64.sha256 dans manifest.toml.

À contrôler dans sa sortie : la ligne binaire, wwwroot et ressources d'index.html : OK, et le sha256 affiché — c'est celui que le manifeste porte désormais.

A.3 Déposer la release

cd ../mabibli && git tag v0.1.0 && git push origin main --tags

Puis, dans l'interface Gitea : créer la release v0.1.0 sur le dépôt mabibli, et y téléverser build/dist/mabibli-0.1.0-linux-x64.tar.gz.

Vérification, à faire sans être authentifié (autre navigateur, ou curl comme ci-dessous) :

curl -fsSLI "https://git.akbar.nohost.me/mathieu/mabibli/releases/download/v0.1.0/mabibli-0.1.0-linux-x64.tar.gz" | head -1

Attendu : HTTP/2 200. Un 404 signifie soit que la release n'est pas déposée, soit que le dépôt est privé — les deux se ressemblent, commencer par vérifier la visibilité.

A.4 Pousser le paquet

⚠️ L'étape la plus facile à oublier. yunohost app install <url> lit le manifeste depuis Gitea, jamais la copie locale : un manifeste corrigé mais non poussé n'existe pas pour le serveur.

cd ../mabibli_ynh && git add -A && git commit -m "Publier la version 0.1.0" && git push

A.5 Installer

sudo yunohost app install https://git.akbar.nohost.me/mathieu/mabibli_ynh --debug

YunoHost demande le domaine (celui créé en A.1) et le groupe autorisé (all_users).

Ce qu'il faut voir passer : Prefetching asset main sur la bonne URL, puis l'installation des fichiers, nginx, systemd, et enfin The service mabibli has correctly executed the action start — le script attend la ligne Application started du journal, ce qui fait échouer franchement l'installation si les migrations EF Core ne passent pas.

A.6 Vérifier

sudo ss -tlnp | grep -i mabibli

Doit montrer 127.0.0.1:<port> uniquement. C'est une frontière de sécurité : sur 0.0.0.0, n'importe qui sur le réseau pourrait forger l'en-tête YNH_USER et se faire passer pour un membre du foyer.

sudo ls -l /home/yunohost.app/mabibli

mabibli.db doit exister : les migrations se sont appliquées seules au premier démarrage. (Pas de -wal ni -shm au repos, c'est normal — SQLite fait un checkpoint à la fermeture de la dernière connexion.)

Enfin, dans un navigateur sur https://mabibli.mondomaine.tld : le portail authentifie, et l'application affiche ton nom d'utilisateur YunoHost — pas « anonyme ». C'est le seul contrôle qui éprouve réellement l'intégration SSO.

---

B. Monter de version — exemple : 0.1.0 → 0.1.1

B.1 Ce qui distingue une version applicative d'une révision de paquet

Ce qui change	Version	Nouvelle archive ?
Le code C#	0.1.0 → 0.1.1~ynh1	oui
Seulement le paquet (conf systemd/nginx, scripts)	0.1.0~ynh1 → 0.1.0~ynh2	non

Le second cas est le plus simple : bump du suffixe ~ynhN à la main dans manifest.toml, commit, push, puis directement l'étape B.5. L'archive et son sha256 ne bougent pas. (C'est ce qui a été fait pour ~ynh2 et ~ynh3.)

La suite décrit le premier cas.

B.2 Compiler et vérifier la nouvelle version

Le code est prêt et committé dans mabibli. Depuis mabibli_ynh :

./build/publier-release.sh --version 0.1.1

⚠️ --version est obligatoire ici. Sans lui, le script déduit la version de manifest.toml et reproduirait 0.1.0. Il remet aussi le suffixe à ~ynh1 : une nouvelle version applicative repart toujours de 1.

Note le sha256 affiché — il ne sera plus jamais le même, même à code identique si les dépendances bougent.

B.3 Tag et release

cd ../mabibli && git tag v0.1.1 && git push origin main --tags

Créer la release v0.1.1 dans Gitea, y téléverser build/dist/mabibli-0.1.1-linux-x64.tar.gz, puis vérifier sans authentification :

curl -fsSLI "https://git.akbar.nohost.me/mathieu/mabibli/releases/download/v0.1.1/mabibli-0.1.1-linux-x64.tar.gz" | head -1

B.4 Pousser le paquet

cd ../mabibli_ynh && git add -A && git commit -m "Publier la version 0.1.1" && git push

B.5 Sauvegarder, puis mettre à jour

YunoHost prend lui-même une sauvegarde de sécurité avant la mise à jour (mabibli-pre-upgrade1), mais elle ne contient pas le répertoire de données (BACKUP_CORE_ONLY) : elle sert à restaurer l'application, pas la bibliothèque. Prendre une sauvegarde complète reste donc utile avant une version qui touche au schéma :

sudo yunohost backup create --apps mabibli

sudo yunohost app upgrade mabibli --debug

(Ajouter --force seulement pour réappliquer une version identique, par exemple en mise au point du paquet.)

Le script arrête le service avant de remplacer les binaires — deux processus sur la même base SQLite pendant une migration est exactement ce qu'il faut éviter — puis attend Application started, avec un délai de 120 s : une migration sur base remplie prend plus de temps que la création d'un schéma vide.

B.6 Vérifier après mise à jour

sudo systemctl status mabibli --no-pager && sudo journalctl -u mabibli -n 30 --no-pager

Puis, dans le navigateur, le contrôle qui compte vraiment : les livres sont toujours là. C'est ce qui valide que la base vit bien dans le répertoire de données et non à côté du binaire — upgrade remplace intégralement /var/www/mabibli.

Vider le cache du navigateur n'est pas nécessaire : le service worker compare les empreintes et propose « Mettre à jour ». Sur mobile, un onglet resté ouvert peut retarder la bascule — c'est précisément ce que le bandeau de mise à jour sert à débloquer.

B.7 Si la mise à jour échoue

YunoHost restaure automatiquement la sauvegarde de sécurité quand le script échoue. Si le service démarre mais que l'application se comporte mal, revenir en arrière à la main :

sudo yunohost backup list

sudo yunohost app remove mabibli --purge

sudo yunohost backup restore <nom-de-l-archive> --apps mabibli

⚠️ --purge efface le répertoire de données. Ne le faire qu'avec une archive contenant la bibliothèque sous la main — celle de B.5, pas mabibli-pre-upgrade1.

---

C. Désinstaller

sudo yunohost app remove mabibli

Retire le service, la conf nginx, la permission SSO, l'utilisateur système, le port et /var/www/mabibli. /home/yunohost.app/mabibli survit, donc la bibliothèque aussi : une désinstallation faite trop vite ne doit pas être irréversible.

⚠️ Corollaire à connaître en phase d'essai : réinstaller après un remove sans purge retrouve l'ancienne base. Ce n'est pas une installation vierge, même si tout le reste est neuf.

Pour tout effacer, données comprises :

sudo yunohost app remove mabibli --purge

Contrôle qu'il ne reste rien :

systemctl status mabibli; sudo ls -d /var/www/mabibli /home/yunohost.app/mabibli 2>&1; getent passwd mabibli

Les trois doivent être négatifs. Le domaine, lui, reste déclaré dans YunoHost.