104 lines
11 KiB
Markdown
104 lines
11 KiB
Markdown
|
# Plan de recette et de déploiement des applications Loutre
|
||
|
|
|
||
|
|
Ce document prépare les opérations ; il ne les autorise pas. Aucun déploiement de production, redémarrage CodexPi, changement QNAP/Jellyfin ou exposition publique ne doit être exécuté sans accord explicite.
|
||
|
|
|
||
|
|
## 1. Conditions d'entrée
|
||
|
|
|
||
|
|
Une application peut entrer en recette uniquement si sa branche contient un commit identifié, si son worktree est propre hors artefacts ignorés, si ses tests métier et son build passent à nouveau depuis ce commit et si ses limites matérielles sont documentées. Le statut reste au maximum `TESTING` avant cette recette.
|
||
|
|
|
||
|
|
Pour les connecteurs QNAP, Jellyfin, Docker, SMB, Home Assistant ou réseau, la recette commence avec des fixtures et un compte ou jeton de lecture seule. Une simulation doit être étiquetée comme telle dans l'interface. Aucun média, virtual host, certificat, appareil ou montage n'est modifié pendant cette étape.
|
||
|
|
|
||
|
|
## 2. Sauvegardes avant changement
|
||
|
|
|
||
|
|
1. Arrêter toute nouvelle tâche de déploiement et attendre la fin de la session Codex active.
|
||
|
|
2. Enregistrer le SHA de CodexPi, le SHA de l'application et les versions d'images actuellement actives.
|
||
|
|
3. Copier les bases SQLite avec leur méthode de sauvegarde cohérente (`VACUUM INTO` ou API de sauvegarde SQLite), puis vérifier `PRAGMA integrity_check` sur la copie.
|
||
|
|
4. Sauvegarder les volumes applicatifs concernés sans inclure les jetons, cookies ou profils dans les journaux de preuve.
|
||
|
|
5. Exporter la configuration Compose résolue en masquant les variables sensibles.
|
||
|
|
6. Pour le reverse proxy QNAP, obtenir séparément une sauvegarde en lecture seule des fichiers autorisés. Aucune écriture NAS n'est incluse dans le déploiement CodexPi.
|
||
|
|
|
||
|
|
Les sauvegardes portent un horodatage UTC et sont conservées hors des worktrees Git. Un test de lecture est obligatoire avant de poursuivre.
|
||
|
|
|
||
|
|
## 3. Recette isolée
|
||
|
|
|
||
|
|
Chaque application est construite depuis son commit dans un projet Compose distinct, avec un nom de projet unique, un volume de recette neuf et un port lié uniquement à `127.0.0.1`. Une seule application lourde est démarrée à la fois sur le Raspberry Pi.
|
||
|
|
|
||
|
|
La recette vérifie :
|
||
|
|
|
||
|
|
- santé HTTP et démarrage sans migration destructive ;
|
||
|
|
- authentification et isolation entre utilisateurs ;
|
||
|
|
- création, modification, réouverture après redémarrage et suppression lorsque prévue ;
|
||
|
|
- erreurs de validation et indisponibilité des connecteurs ;
|
||
|
|
- build frontend, navigation mobile 390 px et absence d'erreur JavaScript ;
|
||
|
|
- absence de bouton essentiel fictif ;
|
||
|
|
- persistance sur le volume de recette ;
|
||
|
|
- limites CPU/RAM et taille des journaux ;
|
||
|
|
- export/import ou sauvegarde spécifique à l'application ;
|
||
|
|
- URL interne d'ouverture depuis le catalogue CodexPi.
|
||
|
|
|
||
|
|
Les applications d'infrastructure comparent les valeurs affichées à la source autorisée. Une valeur issue d'une fixture ne valide jamais le connecteur réel.
|
||
|
|
|
||
|
|
## 4. Passage contrôlé
|
||
|
|
|
||
|
|
Après présentation des preuves, l'utilisateur choisit explicitement l'application et la fenêtre de déploiement. Le changement utilise une nouvelle image immuable étiquetée avec le SHA, puis un remplacement ciblé du seul service concerné. Il n'inclut jamais `docker compose down -v`, un redémarrage du Pi/NAS, une modification SSH/pare-feu ou une modification automatique du reverse proxy QNAP.
|
||
|
|
|
||
|
|
Les contrôles immédiats sont : santé, connexion, lecture de données existantes, écriture d'une donnée de contrôle réversible, réouverture, journaux sans secret et lien « Ouvrir » du catalogue. `READY_V0` n'est attribué qu'après leur réussite.
|
||
|
|
|
||
|
|
## 5. Rollback
|
||
|
|
|
||
|
|
Le rollback restaure l'image précédente et la configuration Compose précédente. Si une migration de données a été appliquée, son plan spécifique doit être testé avant le déploiement ; à défaut, l'application repasse en lecture seule et la base sauvegardée est restaurée dans un volume distinct pour comparaison. Les volumes actuels ne sont jamais supprimés automatiquement.
|
||
|
|
|
||
|
|
Un échec de santé, une perte d'authentification, une erreur de persistance, une consommation anormale ou une divergence avec une source réelle déclenche le rollback. L'incident et les commandes réellement exécutées sont ajoutés à l'historique, sans valeur secrète.
|
||
|
|
|
||
|
|
## 6. Ordre proposé
|
||
|
|
|
||
|
|
1. PWA Factory, déjà en `TESTING`.
|
||
|
|
2. Pi Doctor en mode collecte/diagnostic uniquement.
|
||
|
|
3. LoutreOS en lecture seule.
|
||
|
|
4. Codex Commander et Autonomous Dev Studio.
|
||
|
|
5. Applications CRUD locales : LoutreFinance, Smart Inventory, AutoCare, Knowledge Graph, PrintPilot, TripOrganizer et LoutreHome.
|
||
|
|
6. Connecteurs réseau ou externes : NetworkGuardian, LoutreBrain, Reverse Proxy Manager et modules NASFLIX.
|
||
|
|
|
||
|
|
Cet ordre limite les risques : les intégrations QNAP, réseau et médias restent les dernières et conservent leur mode lecture seule tant qu'une validation séparée n'est pas accordée.
|
||
|
|
|
||
|
|
## 7. Registre et workflow préparé
|
||
|
|
|
||
|
|
Le registre central `application_registry` contient exactement les 17 applications métier ; le portail App Store reste un composant de CodexPi et n'est pas compté comme une dix-huitième application. Chaque ligne conserve l'identifiant du portefeuille, le type, le répertoire cible, le commit, les stacks backend/frontend, l'URL interne, la route d'ouverture, les preuves de tests, les dépendances, le statut et les limites de déploiement.
|
||
|
|
|
||
|
|
Les statuts de mise en service sont distincts des statuts de développement :
|
||
|
|
|
||
|
|
- `DEVELOPMENT_READY` : code récupérable, mais V0 ou preuves encore incomplètes ;
|
||
|
|
- `TESTING` : validations isolées en cours ou terminées sans recette cible ;
|
||
|
|
- `INTEGRATION_READY` : commit, tests métier, persistance et route prêts pour recette ;
|
||
|
|
- `DEPLOYED` : révision réellement démarrée dans l'environnement déclaré ;
|
||
|
|
- `OPERATIONAL` : healthchecks, route, HTTPS et scénarios métier vérifiés sur la cible ;
|
||
|
|
- `BLOCKED` : preuve ou dépendance indispensable absente.
|
||
|
|
|
||
|
|
Les API `/api/application-registry` et `/api/application-registry/mission` exposent respectivement le registre et la supervision de la file. La préparation d'un déploiement crée un enregistrement `PREPARED` et dix étapes persistantes : sauvegarde, dépendances, migrations, configuration, démarrage, healthcheck, routes, HTTPS, smoke test et rollback. Elle n'exécute aucune commande. Une cible doit être privée, le commit doit correspondre au registre et une préparation de production exige `INTEGRATION_READY`.
|
||
|
|
|
||
|
|
Les plans LoutreOS, Pi Doctor, Reverse Proxy Manager et NASFLIX embarquent en plus une liste structurée de contrôles de connecteurs. Chaque contrôle précise le mode autorisé (`read-only`, Docker rootless, diagnostic uniquement ou brouillon) et la preuve attendue. Ces lignes restent des exigences de recette : leur présence dans un plan ne signifie jamais que le Raspberry Pi, QNAP ou Jellyfin a été contacté.
|
||
|
|
|
||
|
|
`DEPLOYED` et `OPERATIONAL` ne peuvent pas être saisis manuellement. Leur future promotion devra provenir du workflow exécuté après autorisation, avec preuves attachées à chaque étape. Ainsi, des tests unitaires verts ne suffisent jamais à rendre une application opérationnelle.
|
||
|
|
|
||
|
|
## 8. Tableau de mise en service des 17 applications
|
||
|
|
|
||
|
|
| Projet | Code | Tests | Intégration | Déploiement | Opérationnel |
|
||
|
|
|---|---|---|---|---|---|
|
||
|
|
| LoutreOS | Commit `2021e40`, collecteur/FastAPI/React | 56 backend, 7 frontend, 2 navigateur, persistance et HTTP validés | Route réelle CodexPi et connecteurs Pi/Docker/QNAP/Jellyfin cible manquants | `TESTING`, aucune cible déployée | **NON** — sources réelles externes non testées |
|
||
|
|
| NetworkGuardian | Worktree FastAPI/React existant | 29 backend et build ; parcours cible à refaire | URL CodexPi, découverte autorisée et carte réseau cible manquantes | `DEVELOPMENT_READY` | **NON** — réseau réel non vérifié |
|
||
|
|
| Reverse Proxy Manager | Worktree FastAPI/React et parseur Apache | 25 backend et 6 navigateur conservés | Source QNAP en lecture seule, certificats et workflow de validation manquants | `TESTING` | **NON** — QNAP non connecté |
|
||
|
|
| Codex Commander | Module CodexPi et application isolée existants | 12 backend/build ; navigateur incomplet | Unification, collaboration et reprise réelle à valider | `DEVELOPMENT_READY` | **NON** — session V0 cible non validée |
|
||
|
|
| Autonomous Dev Studio | Module CodexPi fonctionnel partiel | Tests intégrés, aucun parcours complet jusqu'à preview | Versionnement, correction automatique et preview bout en bout manquants | `DEVELOPMENT_READY` | **NON** — aucune application complète produite en recette |
|
||
|
|
| LoutreBrain | Worktree FastAPI/FTS5/React existant | 18 backend et build ; navigateur à refaire | Recherche sémantique, index CodexPi et route réelle manquants | `TESTING` | **NON** — moteur cible non validé |
|
||
|
|
| LoutreFinance | Worktree Django/React existant | 17 Django et 2 navigateur conservés | Revalidation persistance, route CodexPi et recette privée manquantes | `TESTING` | **NON** — aucune cible démarrée |
|
||
|
|
| PrintPilot | Worktree FastAPI/React existant | 37 backend et build | Route, preview et connecteurs matériels explicites manquants | `DEVELOPMENT_READY` | **NON** — aucune imprimante réelle testée |
|
||
|
|
| LoutreHome | Worktree FastAPI/React existant | 14 backend et build | Capteurs/automatisations, route et Home Assistant/MQTT cible manquants | `DEVELOPMENT_READY` | **NON** — données simulées uniquement |
|
||
|
|
| AutoCare | Worktree FastAPI/React existant | 25 backend et build | Route, documents/assurances et preview cible à valider | `DEVELOPMENT_READY` | **NON** — aucune cible démarrée |
|
||
|
|
| Smart Inventory | Worktree FastAPI/React existant | 23 backend et build | Route, photos/documents et restauration cible à valider | `DEVELOPMENT_READY` | **NON** — aucune cible démarrée |
|
||
|
|
| Knowledge Graph | Worktree FastAPI/React/SVG existant | 13 backend et build | Lien LoutreBrain, route et parcours mobile cible manquants | `DEVELOPMENT_READY` | **NON** — aucune cible démarrée |
|
||
|
|
| TripOrganizer | Worktree FastAPI/React existant | 17 backend et build | Documents, carte optionnelle, route et mode hors ligne cible manquants | `DEVELOPMENT_READY` | **NON** — aucune cible démarrée |
|
||
|
|
| PWA Factory | Commit `7f31d2c`, éditeur intégré | Tests CRUD/export ZIP et démarrage de l'export réussis | Recette HTTPS/iPhone et validation visuelle cible manquantes | `TESTING` | **NON** — non déployée et installation iPhone non testée |
|
||
|
|
| NASFLIX MediaHealth | Code partiel dans NASFLIX | Tests connexes uniquement | Rapport, historique, corruption potentielle et Jellyfin réel manquants | `DEVELOPMENT_READY` | **NON** — aucune analyse cible complète |
|
||
|
|
| NASFLIX AI Media Curator | Module NASFLIX partiel | Acceptation dédiée absente | Historique, collections brouillon et Jellyfin cible à valider | `DEVELOPMENT_READY` | **NON** — recommandations cibles non vérifiées |
|
||
|
|
| Pi Doctor | Commit `a5dc22e`, collecteurs, FastAPI/React et module CodexPi | 38 backend, 3 frontend, 4 navigateur, build et HTTP loopback validés | systemd, Docker cible, ingestion CodexPi et session spécialisée réels restent à valider | `TESTING` | **NON** — service hôte non installé et connecteurs réels non testés |
|