9.5 KiB
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_sourceté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 -u https://git.akbar.nohost.me/mathieu/mabibli_ynh --debug
⚠️ L'option -u n'est pas facultative ici. MaBibli n'est pas dans le catalogue
officiel : sans elle, YunoHost ne sait pas où retrouver le paquet et refuse d'emblée —
« mabibli is not in the catalog (anymore?) », puis « No apps can be upgraded ». Rien
n'est cassé pour autant, la commande n'a simplement pas commencé. C'est la même URL
qu'à l'installation, celle du dépôt _ynh, jamais celle de l'archive.
(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.