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 - Contexte technique du projet
flux.md - Architecture des services et flux
deploy.md - Procédures de déploiement détaillées

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

deployment-architecture.md - Architecture de déploiement par phases
best-practices-deployment.md - Bonnes pratiques et interdictions
loki-configuration-guide.md - Configuration Loki obligatoire
scripts-advanced.md - NOUVEAU - Documentation complète des scripts avancés

4. Documents de Déploiement

prompts/prompt-deploy.md - Prompt de déploiement complet

🚨 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)
./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 :

Services applicatifs : Fonctionnent indépendamment du monitoring
Services de monitoring : Observent sans impacter les applications
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

Lire tous les documents de contexte
Vérifier la branche ext
Mettre à jour les dépendances
Synchroniser les configurations

Étape 2: Déploiement

Services applicatifs : ./scripts/start-with-progress.sh
Services de monitoring : ./scripts/start-monitoring.sh
Surveillance : ./scripts/monitor-progress.sh

Étape 3: Validation

Tests des URLs publiques
Vérification des dashboards Grafana
Validation des flux fonctionnels
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

bitcoin → blindbit → sdk_relay : Chaîne blockchain
sdk_relay → lecoffre-back → lecoffre-front : Chaîne applicative
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 :

Consulter les documents de contexte
Vérifier les bonnes pratiques
Utiliser les scripts de diagnostic
Documenter le problème et la solution

Pour améliorer :

Proposer des améliorations dans les REX
Mettre à jour la documentation
Tester les nouvelles approches
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