# Bonnes Pratiques de Déploiement LeCoffre Node

## 🚫 INTERDICTIONS ABSOLUES

### **Commandes Docker Compose Interdites**
```bash
# ❌ 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**
```bash
# ✅ 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)**
```bash
# Ces services peuvent démarrer en parallèle
tor + sdk_storage + sdk_signer + status-api
```

#### **Phase 2: Services Blockchain (Séquentiel)**
```bash
# Chaîne de dépendances blockchain
tor → bitcoin → blindbit → sdk_relay
```

#### **Phase 3: Services Applicatifs (Séquentiel)**
```bash
# 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)**
```bash
# Chaîne de dépendances monitoring
loki → promtail → grafana
```

#### **Phase 5: Services Utilitaires**
```bash
# Services de maintenance
watchtower
```

## 🔧 Utilisation des Scripts

### **Déploiement Complet**
```bash
# 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**
```bash
# Redémarrage monitoring sans impacter les applications
./scripts/start-monitoring.sh
```

### **Diagnostic et Surveillance**
```bash
# 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**
```bash
# ✅ CORRECT
./scripts/start-with-progress.sh
./scripts/start-monitoring.sh

# ❌ INCORRECT
docker compose up -d
```

### **Règle 2: Respecter l'ordre par phases**
```bash
# ✅ 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**
```bash
# ✅ 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**
```bash
# ✅ 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é**
```bash
# ✅ 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 :**
```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

---

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