4NK_env/IA_agents/README.md

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 - NOUVEAU - Analyse architecturale approfondie complète
• ../docs/TECHNICAL_REFERENCE.md - NOUVEAU - Référence technique complète
• ../docs/DEPLOYMENT_GUIDE.md - NOUVEAU - Guide de déploiement complet
• ../docs/ARCHITECTURE_ANALYSIS.md - Analyse architecturale complète
• ../docs/context.md - Contexte technique du projet
• ../docs/flux.md - Architecture des services et flux
• deployment-architecture.md - Architecture de déploiement par phases

2. Documents de Processus

• CI_TRIGGER_PROCESS.md - Processus de déclenchement des CI
• monitoring-progress.md - Système de monitoring et progression
• quick-reference-monitoring.md - Guide de référence rapide

3. Documents d'Architecture

• ../docs/DEEP_ARCHITECTURE_ANALYSIS.md - NOUVEAU - Analyse architecturale approfondie complète
• ../docs/ARCHITECTURE_ANALYSIS.md - Analyse architecturale complète 4NK + LeCoffre
• deployment-architecture.md - Architecture de déploiement par phases
• best-practices-deployment.md - Bonnes pratiques et interdictions
• 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 - 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 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 projects/lecoffre/lecoffre_node/scripts/sync-ignore-files.sh

Portée:

• 4NK_modules/* (exclu: 4NK_vault)
• projects/*/*

🚨 RÈGLES CRITIQUES

🚫 INTERDICTIONS ABSOLUES

# ❌ JAMAIS utiliser ces commandes
docker compose --env-file .env.master up -d
docker compose up -d
docker compose start

✅ OBLIGATIONS ABSOLUES

# ✅ 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

🔍 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 :

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 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 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 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/