Écrire la marche à suivre : mise en production et montée de version
PUBLICATION.md donne les gestes pas à pas, avec le contrôle attendu à chaque étape : première mise en production, montée de version (0.1.0 → 0.1.1), retour arrière si la mise à jour échoue, désinstallation. Deux points qui se paient cher s'ils sont oubliés y sont explicites : `--version` est obligatoire pour une nouvelle version applicative (sans lui le script reproduit celle du manifeste), et la sauvegarde de sécurité pré-upgrade ne contient PAS le répertoire de données. README et A_FAIRE renvoient au fichier plutôt que de tripler la procédure. Dernière URL fictive éliminée : gitea.exemple.org subsistait dans l'exemple CI de publier-release.sh. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
mathieu
+256
@@ -0,0 +1,256 @@
|
||||
# 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 :
|
||||
|
||||
```bash
|
||||
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`) :
|
||||
|
||||
```bash
|
||||
./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
|
||||
|
||||
```bash
|
||||
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) :
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
cd ../mabibli_ynh && git add -A && git commit -m "Publier la version 0.1.0" && git push
|
||||
```
|
||||
|
||||
## A.5 Installer
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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.
|
||||
|
||||
```bash
|
||||
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` :
|
||||
|
||||
```bash
|
||||
./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
|
||||
|
||||
```bash
|
||||
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 :
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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 :
|
||||
|
||||
```bash
|
||||
sudo yunohost backup create --apps mabibli
|
||||
```
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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 :
|
||||
|
||||
```bash
|
||||
sudo yunohost backup list
|
||||
```
|
||||
|
||||
```bash
|
||||
sudo yunohost app remove mabibli --purge
|
||||
```
|
||||
|
||||
```bash
|
||||
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
|
||||
|
||||
```bash
|
||||
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 :
|
||||
|
||||
```bash
|
||||
sudo yunohost app remove mabibli --purge
|
||||
```
|
||||
|
||||
Contrôle qu'il ne reste rien :
|
||||
|
||||
```bash
|
||||
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.
|
||||
Reference in New Issue
Block a user