266 lines
9.8 KiB
Markdown
266 lines
9.8 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)**
|
||
- [`../docs/DEEP_ARCHITECTURE_ANALYSIS.md`](../docs/DEEP_ARCHITECTURE_ANALYSIS.md) - **NOUVEAU** - Analyse architecturale approfondie complète
|
||
- [`../docs/TECHNICAL_REFERENCE.md`](../docs/TECHNICAL_REFERENCE.md) - **NOUVEAU** - Référence technique complète
|
||
- [`../docs/DEPLOYMENT_GUIDE.md`](../docs/DEPLOYMENT_GUIDE.md) - **NOUVEAU** - Guide de déploiement complet
|
||
- [`../docs/ARCHITECTURE_ANALYSIS.md`](../docs/ARCHITECTURE_ANALYSIS.md) - Analyse architecturale complète
|
||
- [`../docs/context.md`](../docs/context.md) - Contexte technique du projet
|
||
- [`../docs/flux.md`](../docs/flux.md) - Architecture des services et flux
|
||
- [`deployment-architecture.md`](deployment-architecture.md) - Architecture de déploiement par phases
|
||
|
||
### **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**
|
||
- [`../docs/DEEP_ARCHITECTURE_ANALYSIS.md`](../docs/DEEP_ARCHITECTURE_ANALYSIS.md) - **NOUVEAU** - Analyse architecturale approfondie complète
|
||
- [`../docs/ARCHITECTURE_ANALYSIS.md`](../docs/ARCHITECTURE_ANALYSIS.md) - Analyse architecturale complète 4NK + LeCoffre
|
||
- [`deployment-architecture.md`](deployment-architecture.md) - Architecture de déploiement par phases
|
||
- [`best-practices-deployment.md`](best-practices-deployment.md) - Bonnes pratiques et interdictions
|
||
- [`blindbit-oracle-deployment.md`](blindbit-oracle-deployment.md) - Déploiement et configuration BlindBit Oracle
|
||
|
||
#### État d'avancement (services)
|
||
- ✅ Ajout et publication du service `4NK_certificator` (ancrage mensuel on-chain)
|
||
- Repo: `https://git.4nkweb.com/4nk/4NK_certificator`
|
||
- Spécification: `docs/CERTIFICATOR_SPECIFICATION.md`
|
||
- Déploiement: `lecoffre_node/docker-compose.certificator.yml`
|
||
|
||
### **4. Documents de Déploiement**
|
||
- [`prompts/prompt-deploy.md`](prompts/prompt-deploy.md) - Prompt de déploiement complet
|
||
- **Scripts centralisés** : Tous les scripts d'agents IA sont maintenant dans `projects/lecoffre/lecoffre_node/scripts/`
|
||
|
||
## 🔐 Synchronisation des configurations (Vault)
|
||
|
||
```bash
|
||
bash projects/lecoffre/lecoffre_node/scripts/sync-vault-full.sh
|
||
```
|
||
Résultats attendus:
|
||
- `vault/confs2/` (miroir local)
|
||
- `confs/` (copie centralisée)
|
||
- `projects/lecoffre/lecoffre_node/confs/` (réplication projet)
|
||
|
||
## 🧹 Standardisation des fichiers ignore
|
||
|
||
```bash
|
||
bash projects/lecoffre/lecoffre_node/scripts/sync-ignore-files.sh
|
||
```
|
||
Portée:
|
||
- `4NK_modules/*` (exclu: `4NK_vault`)
|
||
- `projects/*/*`
|
||
|
||
## 🚨 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 (NOUVEAU - centralisés)
|
||
cd projects/lecoffre/lecoffre_node
|
||
./scripts/start.sh # Démarrage séquentiel avec progression
|
||
./scripts/validate-deployment.sh # Validation complète
|
||
./scripts/maintenance.sh # Menu de maintenance interactif
|
||
./scripts/backup-data.sh # Sauvegarde des données
|
||
./scripts/update-images.sh # Mise à jour sécurisée
|
||
```
|
||
|
||
## 🏗️ 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, status-api
|
||
|
||
Phase 2: Services Blockchain (Séquentiel)
|
||
├── bitcoin → blindbit → sdk_relay
|
||
|
||
Phase 3: Services Applicatifs (Séquentiel)
|
||
├── 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** (centralisés dans `projects/lecoffre/lecoffre_node/scripts/`)
|
||
| 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-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
|
||
|
||
### **Configuration Loki (CRITIQUE)**
|
||
- **OBLIGATOIRE** : `http_listen_address: 0.0.0.0` (pas 127.0.0.1)
|
||
- **OBLIGATOIRE** : `instance_addr: 0.0.0.0` (pas 127.0.0.1)
|
||
- **Fichier** : `/conf/loki/loki-config.yaml` avec configuration complète
|
||
- **Healthcheck** : Utiliser `wget` (pas `curl`)
|
||
|
||
## 🚨 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
|
||
|
||
---
|
||
|
||
## 🔧 Scripts de déploiement (nouveau)
|
||
|
||
Exécuter depuis `4NK_env/`.
|
||
|
||
- Sync des configurations depuis le Vault vers `confs/`:
|
||
```sh
|
||
sh IA_agents/prompts/prompt-deploy/scripts/sync-vault-full.sh
|
||
```
|
||
Prérequis: `vault/.env` (VAULT_BASE_URL, VAULT_USER|VAULT_USER_ID, VAULT_ENV).
|
||
|
||
- Déploiement séquencé de tous les services (respect des phases et healthchecks):
|
||
```sh
|
||
sh IA_agents/prompts/prompt-deploy/scripts/deploy-all.sh
|
||
```
|
||
Affiche la progression Tor (bootstrap %), Bitcoin (sync), BlindBit (sync/scan), Relay (scan), puis vérifie ports et URLs internes/externes.
|
||
|
||
- Vérification rapide de la santé:
|
||
```sh
|
||
sh IA_agents/prompts/prompt-deploy/scripts/quick-health-check.sh
|
||
```
|
||
|
||
Ces scripts remplacent tout usage d’un `docker compose up` global pour garantir l’ordre par phases et la lisibilité de la progression.
|
||
|
||
### Emplacements standards (déploiement)
|
||
- Confs: `/home/debian/4NK_env/lecoffre_node/confs/`
|
||
- Logs: `/home/debian/4NK_env/lecoffre_node/logs/`
|
||
- Data: `/home/debian/4NK_env/lecoffre_node/data/`
|
||
- Backups: `/home/debian/4NK_env/lecoffre_node/backups/` |