Sauvegarde des porte-documents Tela Botanica

Application web libre pour inventorier et sauvegarder les porte-documents des projets Tela Botanica. Elle comprend une interface HTML/CSS/JavaScript, un backend Python/FastAPI et la création d’archives ZIP64. Le serveur contacte uniquement l’API Cumulus et les pages www.tela-botanica.org/projets/<identifiant>. Il ne modifie aucune ressource Tela Botanica. Licence : GNU AGPL version 3 uniquement (AGPL-3.0-only), voir le fichier LICENSE.

Fonctionnement

1. Choisir un projet dans la liste, le rechercher ou coller son URL publique.
2. L’application parcourt récursivement le porte-documents Cumulus. Un indicateur actualisé en direct affiche les dossiers explorés, les fichiers recensés et leur volume annoncé ; l’analyse peut être annulée. Les erreurs de comptage, les dossiers illisibles et les écarts de volume sont signalés.
3. Choisir les dossiers de premier niveau à inclure. Ils sont cochés par défaut. Les fichiers à la racine disposent d’une case distincte.
4. Le serveur récupère chaque fichier dans un fichier temporaire, vérifie sa taille et son SHA-256, puis l’ajoute au ZIP. Les téléchargements incomplets ne sont jamais ajoutés comme fichiers valides.
5. Le ZIP contient _rapport_sauvegarde_tela.json avec les fichiers inclus et exclus, leurs métadonnées Cumulus, leurs tailles et empreintes, ainsi que les anomalies de l’inventaire et de la sauvegarde.

Une sélection volontairement partielle est complète si tous les fichiers sélectionnés ont été récupérés et si l’inventaire est complet. Sinon l’archive est proposée comme partielle et le rapport indique la cause.

Le CSV data/projets.csv fournit le cache initial du catalogue. L’application le rafraîchit en arrière-plan quand son âge dépasse TELA_CATALOG_TTL_HOURS (7 jours par défaut). Le rafraîchissement relit l’index Cumulus puis vérifie les pages des projets, avec une pause configurable.

Installation locale

Python 3.10 ou plus récent est requis. Sous Ubuntu 24.04 :

python3 -m venv .venv
. .venv/bin/activate
python -m pip install -r requirements.txt

Lancer le serveur de développement :

uvicorn app.main:app --host 127.0.0.1 --port 8000

Ouvrir http://127.0.0.1:8000. La documentation interactive de l’API est disponible sur http://127.0.0.1:8000/docs.

Sur Windows PowerShell, activer l’environnement avec .venv\Scripts\Activate.ps1; sur macOS/Linux, utiliser . .venv/bin/activate.

Tests locaux

Les tests n’appellent pas Tela Botanica et ne téléchargent aucun document :

.venv/bin/python -m unittest discover -s tests -v

Ils couvrent les routes FastAPI par ASGI en mémoire, la reconstruction récursive, les incohérences de compteurs, les chemins dangereux, les collisions, la vérification SHA-256, le contenu du ZIP, les fichiers exclus et la reprise après un téléchargement interrompu. Aucun port réseau n’est ouvert et les réponses Cumulus utilisées par ces tests sont fictives.

Configuration

Les paramètres suivants sont lus au démarrage. Les chemins sont locaux au serveur.

Variable	Valeur par défaut	Rôle
TELA_ROOT_PATH	vide	Préfixe d’URL derrière un proxy ; vide pour l’utilisation locale à la racine
TELA_CUMULUS_API	https://api.tela-botanica.org/service:cumulus:doc	API Cumulus autorisée
TELA_PROJECTS_CSV	data/projets.csv	Cache du catalogue de projets
TELA_WORK_DIR	var/sauvegardes	Archives et fichiers temporaires
TELA_REQUEST_DELAY	0.25 seconde	Pause entre requêtes Cumulus
TELA_CATALOG_DELAY	1 seconde	Pause entre les pages projets vérifiées lors de l’actualisation du catalogue
TELA_REQUEST_TIMEOUT	45 secondes	Délai maximal par requête
TELA_RETRIES	3	Tentatives réseau maximales
TELA_CATALOG_TTL_HOURS	168	Âge avant actualisation du catalogue
TELA_ARCHIVE_RETENTION_HOURS	24	Conservation maximale d’une archive
TELA_MAX_ACTIVE_BACKUPS	1	Nombre maximal de sauvegardes simultanées
TELA_MAX_INVENTORY_FILES	200000	Limite de sécurité pour un inventaire
TELA_MAX_INVENTORY_FOLDERS	20000	Limite de sécurité pour un inventaire
TELA_INVENTORY_TIMEOUT_SECONDS	1800	Durée maximale de l’exploration récursive (30 minutes)
TELA_MAX_ARCHIVE_BYTES	50 Gio	Volume annoncé maximal accepté
TELA_DISK_MARGIN_BYTES	64 Mio	Marge d’espace disque en plus de l’archive et du fichier temporaire

Les limites peuvent être remplacées, par exemple :

export TELA_REQUEST_DELAY=0.5
export TELA_ARCHIVE_RETENTION_HOURS=24
export TELA_WORK_DIR=/srv/tela-temp
uvicorn app.main:app --host 127.0.0.1 --port 8000

En local, TELA_ROOT_PATH reste vide et l’interface est disponible à http://127.0.0.1:8000/. Pour l’installation sous le préfixe https://botaphy.fr/save-tela-projets/, définir au démarrage :

export TELA_ROOT_PATH=/save-tela-projets
uvicorn app.main:app --host 127.0.0.1 --port 8000

Le serveur vérifie avant chaque sauvegarde qu’il dispose d’un espace libre suffisant pour l’archive non compressée, le plus gros fichier temporaire et la marge configurée. Les répertoires temporaires gérés par l’application sont nettoyés périodiquement après expiration.

Déploiement

Pour le prototype, lancer un seul processus Uvicorn. Les inventaires et le suivi des tâches sont conservés en mémoire ; plusieurs workers ou plusieurs réplicas ne partagent donc ni les états ni la limite de sauvegardes simultanées. En production, placer l’application derrière un serveur HTTPS, définir un TELA_WORK_DIR dédié avec assez d’espace disque et garder un seul worker tant qu’un stockage partagé des tâches n’est pas ajouté.

Le serveur doit avoir accès en sortie à api.tela-botanica.org et www.tela-botanica.org. Les URL de projet sont validées, les redirections et les liens de téléchargement sont limités à ces hôtes HTTPS. Une limite de dix demandes d’inventaire par adresse IP et par heure protège le service de l’utilisation accidentelle excessive.

Préparation pour botaphy.fr

Ces indications préparent un déploiement ultérieur ; elles ne configurent ni ne modifient le serveur.

• L’application peut être servie sous https://botaphy.fr/save-tela-projets/. TELA_ROOT_PATH doit alors valoir /save-tela-projets ; les chemins de l’interface et le lien d’archive reprennent automatiquement ce préfixe. Laisser cette variable vide pour une utilisation locale à la racine.

• Installer le code depuis le dépôt Forgejo et créer un environnement virtuel Python sur le serveur. Installer les dépendances avec python -m pip install -r requirements.txt.

• Exécuter un seul processus Uvicorn, lié à 127.0.0.1:8000, sous un compte système dédié. Un service systemd permettra son démarrage automatique et son redémarrage après erreur.

• Placer Nginx ou un reverse proxy équivalent devant Uvicorn, avec HTTPS et des délais compatibles avec les inventaires et les téléchargements d’archives. Le port Uvicorn ne doit pas être exposé directement sur Internet.

• Pour Nginx, rediriger le chemin sans slash final et conserver le préfixe dans l’URI transmise à Uvicorn. FastAPI le retire pour le routage grâce à root_path. Exemple à adapter à la configuration du site :

  location = /save-tela-projets {
      return 308 /save-tela-projets/;
  }
  
  location /save-tela-projets/ {
      proxy_set_header Host $host;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      proxy_set_header X-Forwarded-Proto $scheme;
      proxy_read_timeout 3600s;
      proxy_buffering off;
      proxy_pass http://127.0.0.1:8000;
  }
  

• Définir les variables d’environnement dans un fichier protégé hors du dépôt. Configurer TELA_WORK_DIR vers un répertoire dédié, accessible en écriture au compte de service et situé hors de la racine publique du site Hugo. Cela évite que les archives temporaires soient servies comme fichiers statiques.

• Dimensionner l’espace disque en fonction de TELA_MAX_ARCHIVE_BYTES, du plus gros document téléchargé simultanément et de TELA_DISK_MARGIN_BYTES. Surveiller l’espace libre et conserver une seule instance de l’application, car les tâches et la limite de sauvegardes actives sont conservées en mémoire.

• Autoriser les connexions sortantes HTTPS uniquement vers les hôtes Tela Botanica documentés ci-dessus ; conserver la temporisation, les limites de taille et la rétention temporaire des archives.

• Après publication du dépôt Forgejo et avant l’ouverture publique du service, ajouter dans l’interface un accès visible au code source publié, ainsi que les mentions de licence et d’absence de garantie requises par la licence AGPL. La GNU AGPL prévoit un accès au code source correspondant pour les utilisateurs qui interagissent avec une version modifiée à distance.

Le dépôt à publier comprend l’application (app/), le catalogue public initial (data/projets.csv), les tests, requirements.txt, ce README, LICENSE et .gitignore. Les éléments locaux ou exploratoires — environnements virtuels, archives, roues téléchargées, répertoire temporaire et anciens scripts ABBA — ne font pas partie de la publication.

Limites actuelles

• La progression d’une sauvegarde et les inventaires en mémoire sont perdus si le processus serveur redémarre. Le ZIP achevé reste sur disque jusqu’au nettoyage, mais son lien temporaire n’est plus connu après redémarrage.
• L’annulation d’un inventaire est coopérative : si une requête Cumulus est en cours, elle se termine ou atteint son délai réseau (45 secondes par défaut) avant que l’exploration ne s’arrête.
• L’actualisation du catalogue peut prendre quelques minutes, car les pages des projets sont vérifiées une par une avec temporisation.
• Le prototype n’a pas encore été testé sur le serveur de production ni sur des porte-documents réels complets. Les tests utilisent des réponses fictives.
• Aucun téléchargement intégral de projet Tela Botanica n’a été lancé pendant le développement.
• Les documents nécessitant une authentification ne sont pas contournés. Une réponse d’accès refusé apparaît comme une erreur et rend la sauvegarde incomplète.

Structure

app/
  archive.py       vérification, chemins sûrs, ZIP64 et rapport
  config.py        paramètres
  cumulus.py       client HTTP Cumulus en lecture seule
  main.py          API FastAPI, tâches et téléchargement
  models.py        inventaire récursif
  projects.py      cache et actualisation des projets
  static/          interface HTML, CSS et JavaScript
data/projets.csv   cache initial issu des correspondances connues
tests/             tests unitaires sans accès réseau