Raccourcit doc/ADMIN.md a ce qu'un administrateur doit faire
Le fichier expliquait POURQUOI les choix avaient ete faits — le mode WAL mesure a 4 Ko contre 205 Ko, la justification du domaine entier, la portee commune ou personnelle de chaque donnee. Ces raisons ont leur place dans le README du depot du code, pas dans un panneau que YunoHost affiche apres installation. Ne restent que les gestes : ou sont les donnees, ou se reglent les acces, la commande de sauvegarde manuelle correcte, et ce dont le serveur a besoin pour fonctionner. 82 lignes -> 47. ⚠ L'acces sortant vers catalogue.bnf.fr et openlibrary.org est conserve : c'est le seul endroit du projet ou il soit documente. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
mathieu
+26
-61
@@ -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).
|
||||
|
||||
Reference in New Issue
Block a user