4NK_env/IA_agents/best-practices-deployment.md

Bonnes Pratiques de Déploiement LeCoffre Node

🚫 INTERDICTIONS ABSOLUES

Commandes Docker Compose Interdites

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

Pourquoi ces commandes sont interdites ?

1. Pas de phases : Démarrent tous les services en parallèle
2. Dépendances ignorées : Ne respectent pas l'ordre critique
3. Monitoring bloqué : Services de monitoring dépendent des applications
4. Diagnostic difficile : Pas de suivi de progression
5. Échecs cachés : Erreurs non visibles

✅ OBLIGATIONS ABSOLUES

Scripts OBLIGATOIRES

# ✅ Démarrage complet avec phases
./scripts/start-with-progress.sh

# ✅ Démarrage monitoring indépendant
./scripts/start-monitoring.sh

# ✅ Surveillance
./scripts/monitor-progress.sh
./scripts/watch-progress.sh
./scripts/logs-with-progress.sh

Pourquoi ces scripts sont obligatoires ?

1. Phases respectées : Ordre de démarrage optimisé
2. Dépendances gérées : Attente des services critiques
3. Monitoring indépendant : Ne bloque pas les applications
4. Progression visible : Suivi en temps réel
5. Diagnostic facilité : Logs et statuts détaillés

🏗️ Architecture de Déploiement

Principe Fondamental

Services Applicatifs ←→ Services de Monitoring
        ↓                      ↓
   Fonctionnent             Observent sans
  indépendamment            impacter

Ordre par Phases

Phase 1: Services de Base (Parallèle)

# Ces services peuvent démarrer en parallèle
tor + sdk_storage + sdk_signer + status-api

Phase 2: Services Blockchain (Séquentiel)

# Chaîne de dépendances blockchain
tor → bitcoin → blindbit → sdk_relay

Phase 3: Services Applicatifs (Séquentiel)

# Chaîne de dépendances applicatives
sdk_relay → lecoffre-back → lecoffre-front
sdk_relay + sdk_storage → ihm_client

Phase 4: Services de Monitoring (Séquentiel, Indépendant)

# Chaîne de dépendances monitoring
loki → promtail → grafana

Phase 5: Services Utilitaires

# Services de maintenance
watchtower

🔧 Utilisation des Scripts

Déploiement Complet

# 1. Démarrage services applicatifs
./scripts/start-with-progress.sh

# 2. Démarrage monitoring indépendant
./scripts/start-monitoring.sh

# 3. Surveillance
./scripts/monitor-progress.sh

Redémarrage Monitoring Seul

# Redémarrage monitoring sans impacter les applications
./scripts/start-monitoring.sh

Diagnostic et Surveillance

# Aperçu général
./scripts/monitor-progress.sh

# Surveillance temps réel
./scripts/watch-progress.sh

# Logs avec progression
./scripts/logs-with-progress.sh bitcoin -p -f

📊 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

4. Développement

• Tests isolés : Applications testables sans monitoring
• Débogage facilité : Logs et progression détaillés
• Déploiement progressif : Phases de validation

🎯 Règles d'Or pour les Agents IA

Règle 1: Toujours utiliser les scripts spécialisés

# ✅ CORRECT
./scripts/start-with-progress.sh
./scripts/start-monitoring.sh

# ❌ INCORRECT
docker compose up -d

Règle 2: Respecter l'ordre par phases

# ✅ CORRECT : Phases séparées
Phase 1 → Phase 2 → Phase 3 → Phase 4 → Phase 5

# ❌ INCORRECT : Tout en parallèle
tous_les_services_en_même_temps

Règle 3: Monitoring indépendant

# ✅ CORRECT : Monitoring séparé
./scripts/start-with-progress.sh  # Applications
./scripts/start-monitoring.sh     # Monitoring

# ❌ INCORRECT : Monitoring dépendant
applications_dépendent_de_monitoring

Règle 4: Surveillance continue

# ✅ CORRECT : Suivi de progression
./scripts/monitor-progress.sh
./scripts/watch-progress.sh

# ❌ INCORRECT : Démarrage sans suivi
docker_compose_up_et_oublier

Règle 5: Diagnostic facilité

# ✅ CORRECT : Logs avec progression
./scripts/logs-with-progress.sh bitcoin -p -f

# ❌ INCORRECT : Logs bruts
docker logs bitcoin

🔍 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

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)
• RECOMMANDÉ : min_ready_duration: 5s pour l'ingester
• Fichier : /conf/loki/loki-config.yaml avec configuration complète

📝 Validation et Tests

Tests de Déploiement

1. Services applicatifs : URLs publiques accessibles
2. Services de monitoring : Dashboards Grafana alimentés
3. Dépendances : Chaîne de démarrage respectée
4. Performance : Temps de démarrage optimisé

Tests de Maintenance

1. Redémarrage monitoring : Applications non impactées
2. Redémarrage applications : Monitoring non impacté
3. Pannes sélectives : Récupération isolée
4. Surveillance : Détection et diagnostic facilités

🚨 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

---

Document créé le 2025-09-21 Version : 1.0 Usage : Obligatoire pour tous les agents IA