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 :

```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 -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

```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.