# Guide de Déploiement Complet - 4NK Environment

**Date** : 2025-01-27
**Version** : 2.0
**Contexte** : Guide de déploiement complet pour les agents IA et l'équipe de développement

## 📋 Vue d'ensemble du Déploiement

Ce guide présente le processus de déploiement complet de l'environnement 4NK, incluant tous les modules, le projet LeCoffre, et le système de monitoring.

## 🚀 Prérequis et Préparation

### Environnement Système
- **OS** : Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
- **Docker** : 20.10+ avec Docker Compose 2.0+
- **RAM** : Minimum 8 GB, 16 GB recommandé
- **Stockage** : Minimum 100 GB pour la blockchain et les données
- **Réseau** : Connexion stable à Internet

### Accès et Authentification
- **SSH** : Clés SSH configurées pour git.4nkweb.com
- **Docker Registry** : Accès à git.4nkweb.com/4nk/
- **Certificats** : Certificats SSL pour HTTPS (auto-signés en dev)

### Variables d'Environnement
- **Fichier principal** : `.env.master` dans la racine du projet
- **Synchronisation** : 4NK_vault synchronise vers `confs/`
- **Protection** : Fichiers .env inaccessibles pour des raisons de sécurité

## 🏗️ Architecture de Déploiement par Phases

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

### Phase 1: Services de Base (Parallèle)
Ces services peuvent démarrer en parallèle car ils sont indépendants :

| Service | Port | Dépendance | Script | Description |
|---------|------|------------|--------|-------------|
| **tor** | 9050 | Aucune | `start.sh` | Proxy anonyme |
| **sdk_storage** | 8081 | Aucune | `start.sh` | Stockage temporaire |
| **status-api** | 3006 | Aucune | `start.sh` | API de statut |

### Phase 2: Services Blockchain (Séquentiel)
Ces services suivent la chaîne blockchain :

| Service | Port | Dépendance | Script | Description |
|---------|------|------------|--------|-------------|
| **bitcoin** | 8332 | tor (healthy) | `start.sh` | Nœud Bitcoin Signet |
| **blindbit** | 8000 | bitcoin (healthy) | `start.sh` | Oracle Bitcoin |
| **sdk_relay** | 8090-8091 | blindbit (healthy) | `start.sh` | Relais WebSocket |

### Phase 3: Services Applicatifs (Séquentiel)
Ces services suivent la chaîne applicative :

| Service | Port | Dépendance | Script | Description |
|---------|------|------------|--------|-------------|
| **lecoffre-front** | 3004 | sdk_relay + sdk_storage | `start.sh` | Frontend Next.js |
| **ihm_client** | 3003 | sdk_relay + sdk_storage | `start.sh` | Interface utilisateur |

### Phase 4: Services de Monitoring (Séquentiel, Indépendant)
Ces services sont indépendants des applications :

| Service | Port | Dépendance | Script | Description |
|---------|------|------------|--------|-------------|
| **loki** | 3100 | Aucune | `start-monitoring.sh` | Collecte de logs |
| **promtail** | 9080 | loki (healthy) | `start-monitoring.sh` | Agent de collecte |
| **grafana** | 3005 | loki + promtail (healthy) | `start-monitoring.sh` | Dashboards |

### Phase 5: Services Utilitaires
Services de maintenance et surveillance :

| Service | Port | Dépendance | Script | Description |
|---------|------|------------|--------|-------------|
| **watchtower** | 8080 | Aucune | `start.sh` | Mise à jour automatique |

## 🔧 Scripts de Déploiement

### Scripts OBLIGATOIRES

#### `./scripts/start.sh`
**Usage** : Démarrage complet avec phases
**Fonction** : Démarre les services applicatifs dans l'ordre correct
**Phases** : 1, 2, 3, 5
**Fonctionnalités** :
- Démarrage séquentiel avec progression
- Vérification des variables d'environnement
- Healthchecks informatifs
- Tests d'URLs complets
- Surveillance continue

#### `./scripts/start-monitoring.sh`
**Usage** : Démarrage monitoring indépendant
**Fonction** : Démarre les services de monitoring dans l'ordre correct
**Phases** : 4 uniquement
**Fonctionnalités** :
- Démarrage indépendant du monitoring
- Configuration Loki critique
- Dashboards Grafana

#### `./scripts/validate-deployment.sh`
**Usage** : Validation complète du déploiement
**Fonction** : Vérifie tous les services, volumes, et configurations
**Fonctionnalités** :
- Validation des services
- Validation des volumes
- Validation des URLs publiques
- Validation des WebSockets
- Validation des scripts
- Validation des variables d'environnement

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

## 📊 Flux de Déploiement Complet

### Étape 1: Préparation
1. **Vérifier l'environnement** : Docker, RAM, stockage
2. **Synchroniser les configurations** : 4NK_vault → confs/
3. **Vérifier les variables d'environnement** : .env.master
4. **Préparer les volumes** : Données persistantes

### Étape 2: Déploiement Services Applicatifs
```bash
# Démarrage complet avec phases
./scripts/start.sh
```

**Progression attendue** :
1. **Phase 1** : tor, sdk_storage, status-api (parallèle)
2. **Phase 2** : bitcoin → blindbit → sdk_relay (séquentiel)
3. **Phase 3** : lecoffre-front, ihm_client (séquentiel)
4. **Phase 5** : watchtower (utilitaire)

### Étape 3: Déploiement Monitoring
```bash
# Démarrage monitoring indépendant
./scripts/start-monitoring.sh
```

**Progression attendue** :
1. **loki** : Collecte de logs
2. **promtail** : Agent de collecte
3. **grafana** : Dashboards

### Étape 4: Validation
```bash
# Validation complète
./scripts/validate-deployment.sh
```

**Tests effectués** :
- Services Docker
- Volumes persistants
- URLs publiques
- WebSockets
- Variables d'environnement

## 🔍 Configuration Critique

### 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`
- **Healthcheck** : `wget` (pas `curl`)

### Variables d'Environnement par Service
- **bitcoin** : BITCOIN_RPC_USER, BITCOIN_RPC_PASSWORD, BITCOIN_RPC_PORT
- **blindbit** : BLINDBIT_API_PORT, BITCOIN_RPC_URL
- **sdk_relay** : RELAY_PORT, RELAY_HTTP_PORT, STORAGE_URL
- **sdk_storage** : STORAGE_PORT, STORAGE_DATA_DIR
- **lecoffre-front** : NEXT_PUBLIC_API_URL, NEXT_PUBLIC_4NK_URL, NEXT_PUBLIC_IDNOT_BASE_URL
- **ihm_client** : VITE_API_URL, VITE_4NK_URL, VITE_RELAY_URL
- **grafana** : GF_SECURITY_ADMIN_PASSWORD, GF_DATABASE_TYPE
- **loki** : LOKI_CONFIG_FILE, LOKI_DATA_DIR
- **promtail** : PROMTAIL_CONFIG_FILE, LOKI_URL
- **status-api** : STATUS_API_PORT, STATUS_API_HOST

## 📊 Monitoring et Observabilité

### Stack de Monitoring
- **Grafana** : Dashboards et visualisation
- **Loki** : Collecte et stockage des logs
- **Promtail** : Agent de collecte des logs
- **Watchtower** : Mise à jour automatique

### Dashboards Disponibles
- Vue d'ensemble LeCoffre
- Bitcoin & Miner
- Services Applications
- SDK Services
- Frontend Services

### Logs Centralisés
- **Répertoire** : `/home/debian/4NK_env/projects/lecoffre/lecoffre_node/logs/`
- **Services** : tor, bitcoin, blindbit, sdk_relay, sdk_storage, lecoffre-front, ihm_client, grafana, loki, promtail, status-api
- **Collecte** : Promtail → Loki → Grafana

## 🚨 Dépannage et Maintenance

### Problèmes Courants

#### Services non accessibles
```bash
# Vérifier le statut
docker compose --env-file .env.master -f docker-compose.yml ps

# Vérifier les logs
docker compose --env-file .env.master -f docker-compose.yml logs -f <service>
```

#### Erreurs de configuration
```bash
# Synchroniser les configurations
./scripts/sync-configs.sh

# Vérifier les variables d'environnement
./scripts/validate-deployment.sh
```

#### Problèmes de monitoring
```bash
# Redémarrer le monitoring
./scripts/start-monitoring.sh

# Vérifier la configuration Loki
cat confs/loki/loki-config.yaml
```

### Scripts de Maintenance
- **backup-data.sh** : Sauvegarde des données
- **restore-data.sh** : Restauration des données
- **update-images.sh** : Mise à jour des images
- **collect-logs.sh** : Collecte des logs
- **maintenance.sh** : Menu de maintenance interactif

## 🎯 Bonnes Pratiques

### Règles d'Or pour les Agents IA

#### Règle 1: Toujours utiliser les scripts spécialisés
```bash
# ✅ CORRECT
./scripts/start.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.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/validate-deployment.sh
./scripts/monitor-progress.sh

# ❌ INCORRECT : Démarrage sans suivi
docker_compose_up_et_oublier
```

#### Règle 5: Diagnostic facilité
```bash
# ✅ CORRECT : Logs avec progression
./scripts/collect-logs.sh
./scripts/validate-deployment.sh

# ❌ INCORRECT : Logs bruts
docker logs <service>
```

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

## 🔄 Mise à Jour et Maintenance

### Mise à Jour Automatique
- **Watchtower** : Mise à jour automatique toutes les 30 secondes
- **Images** : Tag `ext` pour toutes les images
- **Configuration** : Synchronisation automatique via 4NK_vault

### Maintenance Préventive
- **Sauvegarde** : `./scripts/backup-data.sh`
- **Logs** : `./scripts/collect-logs.sh`
- **Validation** : `./scripts/validate-deployment.sh`
- **Mise à jour** : `./scripts/update-images.sh`

---

**Document créé le 2025-01-27**
**Version** : 2.0
**Usage** : Guide de déploiement complet pour les agents IA et l'équipe de développement