823aab62d8
- Add deployment architecture with 5 phases (base, blockchain, apps, monitoring, utils) - Create start-monitoring.sh for independent monitoring services startup - Update start-with-progress.sh with phase-based deployment - Add deployment-architecture.md with complete architecture documentation - Add best-practices-deployment.md with mandatory rules and prohibitions - Update prompt-deploy.md with mandatory script usage and phase structure - Update quick-reference-monitoring.md with new architecture - Update monitoring-progress.md with correct startup procedures - Add comprehensive README.md for IA agents with all documentation - Enforce separation between application and monitoring services - Implement Loki → Promtail → Grafana sequential startup for monitoring - Prohibit direct docker compose usage, mandate specialized scripts
193 lines
6.5 KiB
Markdown
193 lines
6.5 KiB
Markdown
# Documentation IA Agents - LeCoffre Node
|
|
|
|
## 📋 Vue d'ensemble
|
|
|
|
Ce répertoire contient toute la documentation nécessaire pour les agents IA travaillant sur le projet LeCoffre Node. Cette documentation est **OBLIGATOIRE** et doit être consultée avant tout déploiement.
|
|
|
|
## 📚 Documents Obligatoires
|
|
|
|
### **1. Documents de Contexte (À lire AVANT tout déploiement)**
|
|
- [`context.md`](context.md) - Contexte technique du projet
|
|
- [`flux.md`](flux.md) - Architecture des services et flux
|
|
- [`deploy.md`](deploy.md) - Procédures de déploiement détaillées
|
|
|
|
### **2. Documents de Processus**
|
|
- [`CI_TRIGGER_PROCESS.md`](CI_TRIGGER_PROCESS.md) - Processus de déclenchement des CI
|
|
- [`monitoring-progress.md`](monitoring-progress.md) - Système de monitoring et progression
|
|
- [`quick-reference-monitoring.md`](quick-reference-monitoring.md) - Guide de référence rapide
|
|
|
|
### **3. Documents d'Architecture (NOUVEAU)**
|
|
- [`deployment-architecture.md`](deployment-architecture.md) - Architecture de déploiement par phases
|
|
- [`best-practices-deployment.md`](best-practices-deployment.md) - Bonnes pratiques et interdictions
|
|
|
|
### **4. Documents de Déploiement**
|
|
- [`prompts/prompt-deploy.md`](prompts/prompt-deploy.md) - Prompt de déploiement complet
|
|
|
|
## 🚨 RÈGLES CRITIQUES
|
|
|
|
### **🚫 INTERDICTIONS ABSOLUES**
|
|
```bash
|
|
# ❌ JAMAIS utiliser ces commandes
|
|
docker compose --env-file .env.master up -d
|
|
docker compose up -d
|
|
docker compose start
|
|
```
|
|
|
|
### **✅ OBLIGATIONS ABSOLUES**
|
|
```bash
|
|
# ✅ Utiliser UNIQUEMENT ces scripts
|
|
./scripts/start-with-progress.sh # Services applicatifs
|
|
./scripts/start-monitoring.sh # Services de monitoring
|
|
./scripts/monitor-progress.sh # Surveillance
|
|
```
|
|
|
|
## 🏗️ Architecture de Déploiement
|
|
|
|
### **Principe Fondamental**
|
|
Les services sont organisés en **5 phases** pour optimiser le démarrage et éviter les dépendances inutiles :
|
|
|
|
1. **Services applicatifs** : Fonctionnent indépendamment du monitoring
|
|
2. **Services de monitoring** : Observent sans impacter les applications
|
|
3. **Dépendances** : Seules les dépendances métier sont respectées
|
|
|
|
### **Ordre par Phases**
|
|
```
|
|
Phase 1: Services de Base (Parallèle)
|
|
├── tor, sdk_storage, sdk_signer, status-api
|
|
|
|
Phase 2: Services Blockchain (Séquentiel)
|
|
├── bitcoin → blindbit → sdk_relay
|
|
|
|
Phase 3: Services Applicatifs (Séquentiel)
|
|
├── lecoffre-back → lecoffre-front, ihm_client
|
|
|
|
Phase 4: Services de Monitoring (Séquentiel, Indépendant)
|
|
├── loki → promtail → grafana
|
|
|
|
Phase 5: Services Utilitaires
|
|
└── watchtower
|
|
```
|
|
|
|
## 🔧 Scripts de Déploiement
|
|
|
|
### **Scripts OBLIGATOIRES**
|
|
| Script | Usage | Phases |
|
|
|--------|-------|--------|
|
|
| `start-with-progress.sh` | Démarrage complet avec phases | 1, 2, 3, 5 |
|
|
| `start-monitoring.sh` | Démarrage monitoring indépendant | 4 |
|
|
| `monitor-progress.sh` | Aperçu des services | Toutes |
|
|
| `watch-progress.sh` | Surveillance temps réel | Toutes |
|
|
| `logs-with-progress.sh` | Logs avec progression | Toutes |
|
|
|
|
### **Scripts INTERDITS**
|
|
- `docker compose up -d` (toute variante)
|
|
- Commandes Docker Compose directes
|
|
|
|
## 📊 Avantages de cette Architecture
|
|
|
|
### **1. Robustesse**
|
|
- **Isolation** : Pannes de monitoring n'impactent pas les applications
|
|
- **Récupération** : Redémarrage sélectif possible
|
|
- **Stabilité** : Services applicatifs fonctionnent même sans monitoring
|
|
|
|
### **2. Performance**
|
|
- **Démarrage optimisé** : Services parallèles quand possible
|
|
- **Dépendances respectées** : Chaîne de démarrage optimale
|
|
- **Monitoring indépendant** : Ne ralentit pas les applications
|
|
|
|
### **3. Maintenance**
|
|
- **Redémarrage sélectif** : Monitoring ou applications séparément
|
|
- **Diagnostic facilité** : Scripts spécialisés par fonction
|
|
- **Surveillance continue** : Progression visible en temps réel
|
|
|
|
## 🎯 Workflow de Déploiement
|
|
|
|
### **Étape 1: Préparation**
|
|
1. Lire tous les documents de contexte
|
|
2. Vérifier la branche `ext`
|
|
3. Mettre à jour les dépendances
|
|
4. Synchroniser les configurations
|
|
|
|
### **Étape 2: Déploiement**
|
|
1. **Services applicatifs** : `./scripts/start-with-progress.sh`
|
|
2. **Services de monitoring** : `./scripts/start-monitoring.sh`
|
|
3. **Surveillance** : `./scripts/monitor-progress.sh`
|
|
|
|
### **Étape 3: Validation**
|
|
1. Tests des URLs publiques
|
|
2. Vérification des dashboards Grafana
|
|
3. Validation des flux fonctionnels
|
|
4. Documentation du retour d'expérience
|
|
|
|
## 📝 Documents de Retour d'Expérience
|
|
|
|
### **Format des REX**
|
|
- **Date** : Format ISO (YYYY-MM-DD)
|
|
- **Agent** : Nom de l'agent IA
|
|
- **Objectif** : But du déploiement
|
|
- **Statut** : Succès/Échec/Partiel
|
|
- **Problèmes** : Difficultés rencontrées
|
|
- **Solutions** : Actions correctives
|
|
- **Leçons** : Apprentissages
|
|
|
|
### **Exemple de REX**
|
|
- [`REX_Deploiement_2025-09-21.md`](REX_Deploiement_2025-09-21.md)
|
|
|
|
## 🔍 Points d'Attention
|
|
|
|
### **Dépendances Critiques**
|
|
1. **bitcoin** → **blindbit** → **sdk_relay** : Chaîne blockchain
|
|
2. **sdk_relay** → **lecoffre-back** → **lecoffre-front** : Chaîne applicative
|
|
3. **loki** → **promtail** → **grafana** : Chaîne monitoring
|
|
|
|
### **Healthchecks**
|
|
- Tous les services ont des healthchecks informatifs
|
|
- Les dépendances attendent que les services soient "healthy"
|
|
- Timeouts adaptés selon la criticité
|
|
|
|
### **Variables d'Environnement**
|
|
- Configuration centralisée dans `.env.master`
|
|
- Tous les scripts utilisent `--env-file .env.master`
|
|
- Pas de fichiers `.env` dispersés
|
|
|
|
## 🚨 Signaux d'Alerte
|
|
|
|
### **Si vous voyez ces commandes, c'est une ERREUR :**
|
|
```bash
|
|
docker compose --env-file .env.master up -d
|
|
docker compose up -d
|
|
docker compose start
|
|
```
|
|
|
|
### **Si vous voyez ces comportements, c'est une ERREUR :**
|
|
- Services de monitoring qui bloquent les applications
|
|
- Démarrage de tous les services en parallèle
|
|
- Absence de suivi de progression
|
|
- Logs sans informations de progression
|
|
|
|
### **Si vous voyez ces résultats, c'est CORRECT :**
|
|
- Phases de démarrage visibles
|
|
- Progression Bitcoin IBD affichée
|
|
- Services de monitoring indépendants
|
|
- Surveillance continue opérationnelle
|
|
|
|
## 📞 Support
|
|
|
|
### **En cas de problème :**
|
|
1. Consulter les documents de contexte
|
|
2. Vérifier les bonnes pratiques
|
|
3. Utiliser les scripts de diagnostic
|
|
4. Documenter le problème et la solution
|
|
|
|
### **Pour améliorer :**
|
|
1. Proposer des améliorations dans les REX
|
|
2. Mettre à jour la documentation
|
|
3. Tester les nouvelles approches
|
|
4. Valider avec l'équipe
|
|
|
|
---
|
|
|
|
**Document créé le 2025-09-21**
|
|
**Version** : 1.0
|
|
**Usage** : Obligatoire pour tous les agents IA
|
|
**Mise à jour** : À chaque déploiement |