diff --git a/doc/ADMIN.md b/doc/ADMIN.md index 473f9dd..ec9b534 100644 --- a/doc/ADMIN.md +++ b/doc/ADMIN.md @@ -1,82 +1,47 @@ -## Comment l'authentification fonctionne - -MaBibli n'a **pas de connexion propre**. L'identité vient entièrement du portail YunoHost : -nginx authentifie le visiteur, puis SSOwat injecte dans la requête les en-têtes `YNH_USER`, -`YNH_USER_EMAIL` et `YNH_USER_FULLNAME`, que l'application se contente de lire. - -Conséquences pratiques : - -- **Qui peut voir la bibliothèque se règle dans les permissions YunoHost** (`mabibli.main`), - pas dans l'application. -- La collection est **commune** à toutes les personnes autorisées. Chaque livre garde une trace - de qui l'a saisi, mais personne n'est cloisonné : c'est une bibliothèque de foyer. -- Les **statuts de lecture sont personnels** (chacun sa progression), les **prêts sont communs** - (un livre absent l'est pour tout le monde). -- Se déconnecter du portail YunoHost ne déconnecte pas nécessairement des applications : - chacune garde sa propre session. C'est une limite connue de YunoHost, pas de MaBibli. - -⚠️ **Ne pas exposer le port interne.** Le service écoute volontairement sur `127.0.0.1` -uniquement. L'application fait confiance à `YNH_USER` parce que SSOwat écrase cet en-tête à -chaque requête ; un service joignable directement permettrait à quiconque de forger -`YNH_USER` et de contourner le portail. Le port n'est pas ouvert au pare-feu, et -`ASPNETCORE_URLS` dans l'unité systemd ne doit jamais être élargi à `0.0.0.0` ou `*`. - -## Domaine entier obligatoire - -MaBibli s'installe **sur un domaine entier**, pas sous un sous-chemin (`/mabibli`). - -Le client est une application Blazor WebAssembly : son chemin de base et les empreintes -d'intégrité de son service worker sont figés **à la compilation**. Comme le paquet installe une -archive déjà compilée — et ne compile jamais rien sur le serveur — il n'existe pas de moyen -propre de les réécrire à l'installation. YunoHost refusera donc un changement d'URL vers un -sous-chemin. - ## Où vivent les données | Quoi | Où | |---|---| -| Binaires et client web | `/var/www/mabibli` (appartient à `root`, l'application ne peut pas s'y écrire) | +| Binaires et client web | `/var/www/mabibli` | | Base SQLite | `/home/yunohost.app/mabibli/mabibli.db` | | Journaux | `journalctl -u mabibli` | -La base est **délibérément séparée des binaires** : une mise à jour remplace intégralement -`/var/www/mabibli` sans jamais toucher aux données. Le schéma est migré automatiquement au -démarrage, il n'y a aucune commande à lancer après une mise à jour. +La base est séparée des binaires : une mise à jour remplace `/var/www/mabibli` sans toucher +aux données, et le schéma est migré automatiquement au démarrage. Rien à lancer à la main. -## Sauvegarde +## Qui a accès -La base tourne en mode **WAL**. C'est important pour qui voudrait bricoler une sauvegarde à la -main : à un instant donné, l'essentiel des données peut se trouver dans `mabibli.db-wal` et -**pas** dans `mabibli.db`. Mesuré sur une base fraîchement migrée, `mabibli.db` faisait 4 Ko — -et ne contenait **aucune table** — pendant que le fichier `-wal` en portait 205 Ko. +MaBibli n'a pas de connexion propre : l'identité vient du portail YunoHost. **Réglez les accès +dans les permissions YunoHost** (`mabibli.main`), pas dans l'application. -Le script de sauvegarde du paquet ne copie donc pas les fichiers tels quels : il demande à -SQLite un instantané cohérent (`.backup`, l'API de sauvegarde en ligne), déposé à côté de la -base sous le nom `mabibli-instantane.db`. C'est ce fichier que la restauration remet en place, -en écartant au passage les `-wal` / `-shm` de l'archive, qui décrivaient l'état d'une autre -copie de la base. +La collection est **commune** à toutes les personnes autorisées. Les statuts de lecture sont +personnels, les prêts sont communs. -Le service **n'est pas arrêté** pendant la sauvegarde : l'API de sauvegarde en ligne garantit la -cohérence du fichier produit sans bloquer les lectures, et couper l'application à chaque -sauvegarde nocturne coûterait une indisponibilité pour rien. +⚠️ **Ne jamais élargir l'écoute du service.** Il écoute sur `127.0.0.1` uniquement, et c'est +une frontière de sécurité : l'application fait confiance à l'en-tête `YNH_USER` parce que +SSOwat l'écrase à chaque requête. Un service joignable directement permettrait de le forger. -Pour une sauvegarde manuelle, la bonne commande est donc : +## Sauvegarde manuelle + +La base est en mode WAL : **un `cp` du fichier `.db` peut ne rien sauvegarder du tout.** ```bash sqlite3 /home/yunohost.app/mabibli/mabibli.db ".backup '/quelque/part/mabibli.db'" ``` -et surtout pas un `cp` du seul fichier `.db`. +`yunohost backup create` fait déjà ce qu'il faut, sans arrêter le service. -## Le scan du code-barres exige HTTPS +## Ce dont le serveur a besoin -L'accès à la caméra n'est autorisé par les navigateurs que dans un contexte sécurisé. En -production, le certificat Let's Encrypt de YunoHost suffit. En revanche, joindre le serveur par -son IP locale (`http://192.168.x.x`) fera **toujours** échouer le scan : ce n'est pas un -contexte sécurisé. La saisie manuelle de l'ISBN reste disponible dans tous les cas. +- **Accès sortant HTTPS** vers `catalogue.bnf.fr` et `openlibrary.org`, pour pré-remplir les + fiches depuis un ISBN. Sans lui l'application marche, mais toute saisie devient manuelle. +- **HTTPS** pour le scan du code-barres : les navigateurs n'ouvrent la caméra qu'en contexte + sécurisé. Le certificat Let's Encrypt de YunoHost suffit ; joindre le serveur par son IP + locale fera toujours échouer le scan. La saisie manuelle reste disponible. +- **Un domaine entier.** MaBibli ne s'installe pas sous un sous-chemin : le client Blazor fige + son chemin de base à la compilation, et rien n'est compilé sur le serveur. -## Accès sortant nécessaire +--- -Le serveur doit pouvoir joindre `catalogue.bnf.fr` et `openlibrary.org` en HTTPS pour -pré-remplir les fiches à partir d'un ISBN. Sans accès sortant, l'application fonctionne, mais -toute saisie devient manuelle. +Le détail — conception du paquet, publication, mise à jour pas à pas, retour arrière — +est dans le [README du dépôt du code](https://git.akbar.nohost.me/mathieu/mabibli#readme).