From 2a2ae3d21af7ad6f2202d58ac4c7d72af2e9cf2e Mon Sep 17 00:00:00 2001 From: LeCoffre Deployment Date: Wed, 1 Oct 2025 20:48:03 +0000 Subject: [PATCH] docs+ops: vault sync workflow; deploy-all with live progress and URL checks; prompt updates --- .cursorignore | 1 + .gitignore | 2 +- .gitmodules | 4 + IA_agents/AGENTS_SYNTHESIS.md | 195 +++++++++++++ IA_agents/README.md | 16 +- README.md | 18 +- docs/ARCHITECTURE_ANALYSIS.md | 315 ++++++++++++++++++++ docs/CERTIFICATOR_SPECIFICATION.md | 4 +- docs/DEEP_ARCHITECTURE_ANALYSIS.md | 422 +++++++++++++++++++++++++++ docs/DEPLOYMENT_GUIDE.md | 330 +++++++++++++++++++++ docs/DOCUMENTATION_SYNTHESIS.md | 217 ++++++++++++++ docs/README-URL-TESTS.md | 24 +- docs/TECHNICAL_REFERENCE.md | 406 ++++++++++++++++++++++++++ docs/flux.md | 4 +- projects/lecoffre/lecoffre-back-mini | 1 + 15 files changed, 1932 insertions(+), 27 deletions(-) create mode 100644 IA_agents/AGENTS_SYNTHESIS.md create mode 100644 docs/ARCHITECTURE_ANALYSIS.md create mode 100644 docs/DEEP_ARCHITECTURE_ANALYSIS.md create mode 100644 docs/DEPLOYMENT_GUIDE.md create mode 100644 docs/DOCUMENTATION_SYNTHESIS.md create mode 100644 docs/TECHNICAL_REFERENCE.md create mode 160000 projects/lecoffre/lecoffre-back-mini diff --git a/.cursorignore b/.cursorignore index cc0a4ae..3696c7c 100644 --- a/.cursorignore +++ b/.cursorignore @@ -3,3 +3,4 @@ /home/debian/4NK_env/backups/ logs/ backups/ +confs/ \ No newline at end of file diff --git a/.gitignore b/.gitignore index a7301d1..477669d 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,6 @@ # 4NK Environment - Git Ignore # ============================ - +confs/ # Dossiers de sauvegarde des scripts **/backup/ **/*backup* diff --git a/.gitmodules b/.gitmodules index 48b8670..94e6daa 100644 --- a/.gitmodules +++ b/.gitmodules @@ -63,6 +63,10 @@ path = 4NK_modules/4NK_web_status path = projects/lecoffre/lecoffre-front url = git@git.4nkweb.com:4nk/lecoffre-front.git branch = ext +[submodule "lecoffre-back-mini"] + path = projects/lecoffre/lecoffre-back-mini + url = git@git.4nkweb.com:4nk/lecoffre-back-mini.git + branch = ext [submodule "lecoffre_node"] path = projects/lecoffre/lecoffre_node url = git@git.4nkweb.com:4nk/lecoffre_node.git diff --git a/IA_agents/AGENTS_SYNTHESIS.md b/IA_agents/AGENTS_SYNTHESIS.md new file mode 100644 index 0000000..ac4309d --- /dev/null +++ b/IA_agents/AGENTS_SYNTHESIS.md @@ -0,0 +1,195 @@ +# Synthèse pour Agents IA - 4NK Environment + +**Date** : 2025-01-27 +**Version** : 1.0 +**Usage** : Guide de synthèse pour les agents IA travaillant sur l'environnement 4NK + +## 🎯 Contexte Général + +### Environnement de Développement Centralisé +- **Machine principale** : dev4.4nkweb.com (LeCoffre) +- **Nœud de bootstrap** : dev3.4nkweb.com (signer centralisé, mini back) +- **Architecture** : 4NK modules + Projet LeCoffre (notaires) +- **Gestion des configurations** : 4NK_vault (API sécurisée) + +## 🏗️ Architecture 4NK - Modules Principaux + +### Services Core +1. **sdk_relay** (8090/8091) - Relais WebSocket central +2. **sdk_storage** (8081) - Stockage temporaire sécurisé +3. **sdk_signer** - Service de signature TypeScript +4. **sdk_client** - Client SDK (WASM) +5. **sdk_common** - Composants communs +6. **ihm_client** (3003) - Interface de gestion des clés + +### Services Spécialisés +7. **4NK_vault** (6666) - API sécurisée de gestion des configurations +8. **4NK_certificator** - Ancrage cryptographique sur Bitcoin +9. **4NK_miner** - Service de minage (test) +10. **4NK_web_status** - Monitoring et statut +11. **blindbit-oracle** (8000) - Oracle Bitcoin Silent Payments +12. **rust-silentpayments** - Implémentation Silent Payments + +## 🏢 Projet LeCoffre - Architecture Notariale + +### Composants +- **lecoffre_node** - Docker de contrôle (orchestrateur principal) +- **lecoffre-front** - Frontend Next.js (interface notaires) +- **lecoffre-back-mini** - Backend centralisé (APIs externes) + +### URLs et Services +- **LeCoffre Front** : https://dev4.4nkweb.com/lecoffre +- **4NK iframe** : https://dev4.4nkweb.com +- **Signer centralisé** : dev3.4nkweb.com (module 4NK pour notaires) +- **Mini back** : dev3.4nkweb.com (Stripe, Mailchimp, OVH, IdNot) + +## 🔐 4NK_vault - Gestion Centralisée des Configurations + +### Rôle Critique +- **API sécurisée** pour la gestion des configurations +- **Chiffrement quantique résistant** (ChaCha20-Poly1305) +- **Authentification par clés utilisateur** +- **Rotation automatique des clés** (toutes les heures) +- **Synchronisation** vers `confs/` dans le docker de contrôle + +### Sécurité +- **Fichiers .env inaccessibles** pour des raisons de sécurité +- **Variables séparées** des secrets +- **Configurations déployées** dans `confs/` pour visualisation +- **Isolation par environnement** (dev, prod) + +## 🚀 Déploiement par Phases - RÈGLES CRITIQUES + +### ⚠️ INTERDICTIONS ABSOLUES +```bash +# ❌ JAMAIS utiliser ces commandes +docker compose --env-file .env.master up -d +docker compose up -d +docker compose start +``` + +### ✅ SCRIPTS OBLIGATOIRES +```bash +# Démarrage complet avec phases +./scripts/start-with-progress.sh + +# Démarrage monitoring indépendant +./scripts/start-monitoring.sh + +# Surveillance et validation +./scripts/monitor-progress.sh +./scripts/validate-deployment.sh +``` + +### Phases de Déploiement +1. **Phase 1** : Services de base (tor, sdk_storage, status-api) +2. **Phase 2** : Services blockchain (bitcoin → blindbit → sdk_relay) +3. **Phase 3** : Services applicatifs (lecoffre-front, ihm_client) +4. **Phase 4** : Services de monitoring (loki → promtail → grafana) +5. **Phase 5** : Services utilitaires (watchtower) + +## 📊 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 + +### 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` + +## 🔧 Scripts de Gestion + +### Scripts Principaux +- `start.sh` - Démarrage complet avec phases +- `validate-deployment.sh` - Validation du déploiement +- `maintenance.sh` - Menu de maintenance interactif +- `backup-data.sh` - Sauvegarde des données +- `update-images.sh` - Mise à jour sécurisée + +### Scripts de Monitoring +- `monitor-progress.sh` - Aperçu des services +- `watch-progress.sh` - Surveillance temps réel +- `logs-with-progress.sh` - Logs avec progression + +## 📚 Documentation Centralisée + +### Structure +- **IA_agents/** : Documentation pour les agents IA +- **docs/** : Documentation technique centralisée +- **ARCHITECTURE_ANALYSIS.md** : Analyse architecturale complète + +### Documents Obligatoires +1. **ARCHITECTURE_ANALYSIS.md** - Analyse architecturale complète +2. **deployment-architecture.md** - Architecture de déploiement +3. **best-practices-deployment.md** - Bonnes pratiques +4. **README.md** - Documentation principale + +## 🎯 Points Clés pour les Agents IA + +### 1. **Respect des Phases** +- Services applicatifs indépendants du monitoring +- Démarrage séquentiel selon les dépendances +- Monitoring indépendant des applications + +### 2. **Sécurité des Configurations** +- 4NK_vault pour la gestion centralisée +- Fichiers .env inaccessibles +- Configurations synchronisées vers confs/ + +### 3. **Scripts Spécialisés** +- Utilisation obligatoire des scripts fournis +- Interdiction des commandes Docker Compose directes +- Surveillance continue et diagnostic facilité + +### 4. **Architecture Modulaire** +- Modules 4NK : SDK, services, monitoring +- Projet LeCoffre : Interface notariale +- 4NK_vault : Gestion centralisée des configurations + +## 🚨 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 + +## 📞 Support et Ressources + +### En cas de problème : +1. Consulter `DEEP_ARCHITECTURE_ANALYSIS.md` pour l'analyse approfondie complète +2. Consulter `TECHNICAL_REFERENCE.md` pour la référence technique complète +3. Consulter `DEPLOYMENT_GUIDE.md` pour le guide de déploiement complet +4. Consulter `ARCHITECTURE_ANALYSIS.md` pour le contexte complet +5. Vérifier `best-practices-deployment.md` pour les bonnes pratiques +6. Utiliser les scripts de diagnostic spécialisés +7. 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-01-27** +**Version** : 1.0 +**Usage** : Guide de synthèse obligatoire pour tous les agents IA diff --git a/IA_agents/README.md b/IA_agents/README.md index 12279f4..e4b12ac 100644 --- a/IA_agents/README.md +++ b/IA_agents/README.md @@ -7,9 +7,13 @@ Ce répertoire contient toute la documentation nécessaire pour les agents IA tr ## 📚 Documents Obligatoires ### **1. Documents de Contexte (À lire AVANT tout déploiement)** -- [`context.md`](context.md) - Contexte technique du projet -- [`flux.md`](flux.md) - Architecture des services et flux -- [`deploy.md`](deploy.md) - Procédures de déploiement détaillées +- [`../docs/DEEP_ARCHITECTURE_ANALYSIS.md`](../docs/DEEP_ARCHITECTURE_ANALYSIS.md) - **NOUVEAU** - Analyse architecturale approfondie complète +- [`../docs/TECHNICAL_REFERENCE.md`](../docs/TECHNICAL_REFERENCE.md) - **NOUVEAU** - Référence technique complète +- [`../docs/DEPLOYMENT_GUIDE.md`](../docs/DEPLOYMENT_GUIDE.md) - **NOUVEAU** - Guide de déploiement complet +- [`../docs/ARCHITECTURE_ANALYSIS.md`](../docs/ARCHITECTURE_ANALYSIS.md) - Analyse architecturale complète +- [`../docs/context.md`](../docs/context.md) - Contexte technique du projet +- [`../docs/flux.md`](../docs/flux.md) - Architecture des services et flux +- [`deployment-architecture.md`](deployment-architecture.md) - Architecture de déploiement par phases ### **2. Documents de Processus** - [`CI_TRIGGER_PROCESS.md`](CI_TRIGGER_PROCESS.md) - Processus de déclenchement des CI @@ -17,11 +21,11 @@ Ce répertoire contient toute la documentation nécessaire pour les agents IA tr - [`quick-reference-monitoring.md`](quick-reference-monitoring.md) - Guide de référence rapide ### **3. Documents d'Architecture** +- [`../docs/DEEP_ARCHITECTURE_ANALYSIS.md`](../docs/DEEP_ARCHITECTURE_ANALYSIS.md) - **NOUVEAU** - Analyse architecturale approfondie complète +- [`../docs/ARCHITECTURE_ANALYSIS.md`](../docs/ARCHITECTURE_ANALYSIS.md) - Analyse architecturale complète 4NK + LeCoffre - [`deployment-architecture.md`](deployment-architecture.md) - Architecture de déploiement par phases - [`best-practices-deployment.md`](best-practices-deployment.md) - Bonnes pratiques et interdictions -- [`loki-configuration-guide.md`](loki-configuration-guide.md) - Configuration Loki obligatoire -- [`scripts-advanced.md`](scripts-advanced.md) - **NOUVEAU** - Documentation complète des scripts avancés -- [`blindbit-oracle-deployment.md`](blindbit-oracle-deployment.md) - **NOUVEAU** - Déploiement et configuration BlindBit Oracle +- [`blindbit-oracle-deployment.md`](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) diff --git a/README.md b/README.md index 38c621f..2cda103 100644 --- a/README.md +++ b/README.md @@ -63,7 +63,7 @@ cd lecoffre_node | **WebSocket** | ws://localhost/ws/ | Communication temps réel | | **Status Page** | http://localhost/status/ | Tableau de bord | | **Grafana** | http://localhost/grafana/ | Monitoring | -| **Redirections IdNot** | http://dev3.4nkweb.com/ | Redirections externes | +| **Redirections IdNot** | `` | Redirections externes | | **HTTPS** | https://localhost/ | Accès sécurisé | ### Ports @@ -94,11 +94,21 @@ cd lecoffre_node ## 📚 Documentation et Agents IA ### Agents IA - Contexte et outillage complet (IA_agents/) -- **context.md** : Contexte général des projets 4NK et LeCoffre pour les agents IA -- **deploy.md** : Procédures de déploiement détaillées -- **flux.md** : Architecture des flux et services +- **AGENTS_SYNTHESIS.md** : **NOUVEAU** - Synthèse complète pour les agents IA +- **README.md** : Documentation principale et règles obligatoires +- **deployment-architecture.md** : Architecture de déploiement par phases +- **best-practices-deployment.md** : Bonnes pratiques et interdictions - **todo.md** : Liste des tâches et améliorations à suivre +### Documentation Technique (docs/) +- **DEEP_ARCHITECTURE_ANALYSIS.md** : **NOUVEAU** - Analyse architecturale approfondie complète +- **TECHNICAL_REFERENCE.md** : **NOUVEAU** - Référence technique complète +- **DEPLOYMENT_GUIDE.md** : **NOUVEAU** - Guide de déploiement complet +- **DOCUMENTATION_SYNTHESIS.md** : **NOUVEAU** - Synthèse de la documentation +- **ARCHITECTURE_ANALYSIS.md** : Analyse architecturale complète 4NK + LeCoffre +- **context.md** : Contexte général des projets 4NK et LeCoffre +- **flux.md** : Architecture des flux et services + ### Documentation spécifique - **lecoffre_node/README-AUTONOMOUS.md** : Architecture autonome LeCoffre - **doc_api/** : Documentation API 4NK diff --git a/docs/ARCHITECTURE_ANALYSIS.md b/docs/ARCHITECTURE_ANALYSIS.md new file mode 100644 index 0000000..9d40fd0 --- /dev/null +++ b/docs/ARCHITECTURE_ANALYSIS.md @@ -0,0 +1,315 @@ +# Analyse Architecturale Complète - 4NK Environment + +**Date** : 2025-01-27 +**Version** : 1.0 +**Contexte** : Analyse complète de l'architecture 4NK et du projet LeCoffre + +## 📋 Vue d'ensemble + +Cette analyse présente l'architecture complète de l'environnement 4NK, incluant tous les modules 4NK, le projet LeCoffre, et le système de gestion des configurations via 4NK_vault. + +## 🏗️ Architecture Générale + +### Environnement de Développement Centralisé +``` +4NK_env/ # Environnement centralisé +├── 4NK_modules/ # Modules 4NK (SDK, services) +├── projects/lecoffre/ # Projet LeCoffre (notaires) +├── IA_agents/ # Agents IA et documentation +├── docs/ # Documentation centralisée +├── scripts/ # Scripts de gestion centralisés +└── confs/ # Configurations déployées (4NK_vault) +``` + +## 🔧 Modules 4NK - Analyse Complète + +### 1. **sdk_relay** - Service de Relais WebSocket +**Rôle** : Relais central pour les communications WebSocket et la synchronisation mesh +- **Port** : 8090 (WebSocket), 8091 (HTTP health) +- **Fonctionnalités** : + - Serveur WebSocket configurable + - Synchronisation mesh entre relais + - Gestion des processus et membres + - Interface avec Bitcoin Core (RPC + ZMQ) + - Intégration Blindbit pour Silent Payments +- **Dépendances** : Bitcoin Core, Blindbit Oracle +- **Architecture** : Rust avec gestion d'état locale + +### 2. **sdk_storage** - Service de Stockage Temporaire +**Rôle** : Stockage temporaire sécurisé avec TTL +- **Port** : 8081 +- **API** : + - `POST /store` : Stockage avec clé/valeur/TTL + - `GET /retrieve/:key` : Récupération des données +- **Fonctionnalités** : + - Stockage temporaire avec expiration + - Clés hexadécimales 64 caractères + - Valeurs hexadécimales + - TTL optionnel (permanent si non spécifié) + +### 3. **sdk_signer** - Service de Signature +**Rôle** : Service de signature TypeScript pour l'écosystème 4NK +- **Fonctionnalités** : + - Gestion des processus et signatures + - Communication sécurisée + - Compatibilité WASM (stub temporaire) + - Interface avec le réseau de relais +- **Architecture** : TypeScript avec support WASM +- **État** : Compatible avec stub sdk_client + +### 4. **sdk_client** - Client SDK +**Rôle** : Client SDK pour l'interaction avec l'écosystème 4NK +- **Fonctionnalités** : + - Interface avec les services 4NK + - Gestion des connexions WebSocket + - Support des processus et transactions +- **Architecture** : Rust avec interface WebAssembly + +### 5. **sdk_common** - Composants Communs +**Rôle** : Bibliothèque commune partagée entre tous les modules +- **Fonctionnalités** : + - Types et structures communes + - Utilitaires partagés + - Protocoles de communication +- **Usage** : Importé par tous les autres modules + +### 6. **sdk-signer-client** - Client Signeur +**Rôle** : Client pour l'interaction avec le service de signature +- **Fonctionnalités** : + - Interface avec sdk_signer + - Gestion des signatures + - Communication sécurisée + +### 7. **ihm_client** - Interface Homme-Machine +**Rôle** : Interface utilisateur pour la gestion des clés et processus +- **Port** : 3003 +- **Fonctionnalités** : + - Interface de gestion des clés Bitcoin + - Gestion des processus + - Interface utilisateur web +- **Dépendances** : sdk_relay, sdk_storage + +### 8. **4NK_vault** - Système de Gestion des Configurations +**Rôle** : API sécurisée pour la gestion centralisée des configurations +- **Port** : 6666 (HTTPS) +- **Fonctionnalités** : + - Authentification par clés utilisateur + - Chiffrement quantique résistant (ChaCha20-Poly1305) + - Rotation automatique des clés + - Résolution des variables d'environnement + - Isolation par environnement (dev, prod) +- **Sécurité** : + - HTTPS obligatoire + - Authentification par ID utilisateur + - Clés individuelles par utilisateur/environnement + - Rotation automatique (toutes les heures) +- **Déploiement** : Synchronise les configurations vers `confs/` dans le docker de contrôle + +### 9. **4NK_certificator** - Service d'Ancrage Cryptographique +**Rôle** : Ancrage périodique sur Bitcoin mainnet des empreintes des échanges +- **Fonctionnalités** : + - Surveillance des messages du relay 4NK + - Détection des paiements Bitcoin + - Enregistrement périodique sur blockchain + - Métriques de volume de données +- **Architecture** : Rust avec base de données SQLite +- **État** : MVP complet implémenté + +### 10. **4NK_miner** - Service de Minage +**Rôle** : Service de minage Bitcoin (développement/test) +- **Fonctionnalités** : + - Minage sur réseau Signet + - Génération de blocs de test + - Interface avec le réseau Bitcoin + +### 11. **4NK_web_status** - Service de Statut +**Rôle** : Service de monitoring et statut des services +- **Fonctionnalités** : + - Monitoring des services + - Interface de statut + - Métriques de santé + +### 12. **blindbit-oracle** - Oracle Bitcoin +**Rôle** : Service pour les paiements silencieux (Silent Payments) +- **Port** : 8000 +- **Fonctionnalités** : + - Génération d'adresses Silent Payments + - Validation des transactions + - Interface HTTP REST +- **Dépendances** : Bitcoin Core + +### 13. **rust-silentpayments** - Implémentation Silent Payments +**Rôle** : Implémentation Rust des Silent Payments +- **Fonctionnalités** : + - Génération d'adresses Silent Payments + - Validation des transactions + - Utilitaires cryptographiques + +## 🏢 Projet LeCoffre - Architecture Notariale + +### Contexte Métier +Le projet LeCoffre est une plateforme de gestion de documents sécurisée pour les notaires, utilisant l'infrastructure 4NK pour la sécurité et l'intégrité des documents. + +### Composants du Projet LeCoffre + +#### 1. **lecoffre_node** - Orchestrateur Principal +**Rôle** : Docker de contrôle et déploiement pour LeCoffre +- **Architecture** : Docker Compose avec Nginx intégré +- **Services déployés** : + - lecoffre-front (interface utilisateur) + - ihm_client (gestion des clés) + - sdk_relay (relais WebSocket) + - sdk_storage (stockage temporaire) + - bitcoin-signet (nœud Bitcoin) + - blindbit-oracle (oracle Bitcoin) + - tor-proxy (proxy anonyme) + - Services de monitoring (Grafana, Loki, Promtail) +- **Configuration** : Centralisée dans `confs/` (synchronisée depuis 4NK_vault) +- **Déploiement** : Scripts automatisés avec phases de démarrage + +#### 2. **lecoffre-front** - Interface Utilisateur +**Rôle** : Frontend Next.js pour l'application LeCoffre +- **Technologie** : Next.js avec React +- **Fonctionnalités** : + - Interface utilisateur pour les notaires + - Gestion des documents + - Intégration avec l'écosystème 4NK +- **Déploiement** : Conteneur Docker sur port 3004 + +#### 3. **lecoffre-back-mini** - Backend Centralisé +**Rôle** : Backend centralisé pour les besoins spécifiques des notaires +- **Fonctionnalités** : + - APIs avec Stripe (paiements) + - Intégration Mailchimp (email marketing) + - Intégration OVH (SMS) + - Intégration IdNot (HMR dev3 ↔ dev4 via OAuth2) +- **Déploiement** : Sur dev3.4nkweb.com +- **Architecture** : Service centralisé indépendant + +## 🌐 Architecture de Déploiement + +### Environnements +- **dev4.4nkweb.com** : Machine principale (LeCoffre) +- **dev3.4nkweb.com** : Nœud de bootstrap (signer centralisé, mini back) + +### URLs et Services +- **LeCoffre Front** : https://dev4.4nkweb.com/lecoffre +- **4NK iframe** : https://dev4.4nkweb.com +- **Signer centralisé** : dev3.4nkweb.com (module 4NK pour notaires) +- **Mini back** : dev3.4nkweb.com (APIs Stripe, Mailchimp, OVH, IdNot) + +### Architecture de Déploiement 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 (Indépendant) +- loki → promtail → grafana + +#### Phase 5: Services Utilitaires +- watchtower + +## 🔐 Sécurité et Configuration + +### 4NK_vault - Gestion Centralisée des Configurations +- **Rôle** : API sécurisée pour la gestion des configurations +- **Sécurité** : Chiffrement quantique résistant, authentification par clés +- **Déploiement** : Synchronise vers `confs/` dans le docker de contrôle +- **Isolation** : Variables d'environnement protégées, fichiers .env inaccessibles + +### Protection des Secrets +- **Fichiers .env** : Inaccessibles pour des raisons de sécurité +- **Variables** : Séparées des secrets, remplacées dans storage/ +- **Configurations** : Copie déployée dans confs/ pour visualisation + +## 🤖 Agents IA - Organisation + +### Structure IA_agents/ +- **README.md** : Documentation principale et règles obligatoires +- **deployment-architecture.md** : Architecture de déploiement par phases +- **best-practices-deployment.md** : Bonnes pratiques et interdictions +- **prompts/** : Prompts spécialisés pour différents aspects +- **todo.md** : Liste des améliorations et optimisations + +### Règles Critiques pour les Agents IA +1. **Interdictions absolues** : Pas de `docker compose up -d` direct +2. **Scripts obligatoires** : Utilisation des scripts spécialisés +3. **Phases respectées** : Ordre de démarrage par phases +4. **Monitoring indépendant** : Services de monitoring séparés +5. **Surveillance continue** : Suivi de progression obligatoire + +## 📊 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 des images + +### Dashboards Disponibles +- Vue d'ensemble LeCoffre +- Bitcoin & Miner +- Services Applications +- SDK Services +- Frontend Services + +## 🔄 CI/CD et Déploiement + +### Branches et Tags +- **Branche unifiée** : `ext` pour tous les dépôts +- **Tag Docker** : `ext` pour toutes les images +- **Déclenchement** : Push sur `ext` → Build automatique + +### Scripts de Déploiement +- **start.sh** : Démarrage complet avec phases +- **validate-deployment.sh** : Validation du déploiement +- **maintenance.sh** : Menu de maintenance interactif +- **backup-data.sh** : Sauvegarde des données +- **update-images.sh** : Mise à jour sécurisée + +## 📚 Documentation Centralisée + +### Structure docs/ +- **Architecture** : Spécifications techniques +- **Déploiement** : Guides de déploiement +- **Services** : Documentation par service +- **Scripts** : Documentation des scripts + +### Mise à Jour Continue +- **IA_agents/** : Documentation pour les agents IA +- **docs/** : Documentation technique centralisée +- **Alignement** : Synchronisation entre code et documentation + +## 🎯 Points Clés de l'Architecture + +### 1. **Séparation des Responsabilités** +- Services applicatifs indépendants du monitoring +- Monitoring observant sans impacter +- Dépendances uniquement métier + +### 2. **Sécurité Multi-Niveaux** +- 4NK_vault pour la gestion centralisée des configurations +- Chiffrement quantique résistant +- Isolation des secrets et variables + +### 3. **Déploiement Optimisé** +- Phases de démarrage respectées +- Scripts spécialisés obligatoires +- Surveillance continue et diagnostic facilité + +### 4. **Maintenance Facilitée** +- Redémarrage sélectif possible +- Scripts de maintenance interactifs +- Documentation centralisée et à jour + +--- + +**Document créé le 2025-01-27** +**Version** : 1.0 +**Usage** : Documentation architecturale complète pour les agents IA et l'équipe de développement diff --git a/docs/CERTIFICATOR_SPECIFICATION.md b/docs/CERTIFICATOR_SPECIFICATION.md index 3228e0b..1495c36 100644 --- a/docs/CERTIFICATOR_SPECIFICATION.md +++ b/docs/CERTIFICATOR_SPECIFICATION.md @@ -920,7 +920,7 @@ log_level = "info" network = "mainnet" rpc_url = "http://localhost:8332" rpc_user = "bitcoin" -rpc_password = "your_password" +rpc_password = "" wallet_name = "certificator_wallet" min_confirmations = 6 @@ -942,7 +942,7 @@ url = "redis://localhost:6379" cache_ttl_secs = 3600 [api] -jwt_secret = "your_secret_key_here" +jwt_secret = "" cors_allowed_origins = ["https://dev4.4nkweb.com"] ``` diff --git a/docs/DEEP_ARCHITECTURE_ANALYSIS.md b/docs/DEEP_ARCHITECTURE_ANALYSIS.md new file mode 100644 index 0000000..c19ac31 --- /dev/null +++ b/docs/DEEP_ARCHITECTURE_ANALYSIS.md @@ -0,0 +1,422 @@ +# Analyse Architecturale Approfondie - 4NK Environment + +**Date** : 2025-01-27 +**Version** : 2.0 +**Contexte** : Analyse approfondie de l'architecture 4NK et du projet LeCoffre + +## 📋 Vue d'ensemble Détaillée + +Cette analyse approfondie présente l'architecture complète de l'environnement 4NK, incluant tous les modules, leurs dépendances, configurations, et le système de déploiement par phases. + +## 🏗️ Architecture Générale Détaillée + +### Structure des Submodules +``` +4NK_env/ # Environnement centralisé +├── 4NK_modules/ # 13 modules 4NK (SDK, services) +│ ├── sdk_relay/ # Relais WebSocket central (Rust) +│ ├── sdk_storage/ # Stockage temporaire (Rust) +│ ├── sdk_signer/ # Service de signature (TypeScript) +│ ├── sdk_client/ # Client SDK (Rust/WASM) +│ ├── sdk_common/ # Composants communs (Rust) +│ ├── sdk-signer-client/ # Client signeur (TypeScript) +│ ├── ihm_client/ # Interface utilisateur (Vite/React) +│ ├── 4NK_vault/ # API sécurisée configurations (Python) +│ ├── 4NK_certificator/ # Ancrage cryptographique (Rust) +│ ├── 4NK_miner/ # Service de minage (Rust) +│ ├── 4NK_web_status/ # Service de statut (Python) +│ ├── blindbit-oracle/ # Oracle Bitcoin (Rust) +│ ├── rust-silentpayments/ # Silent Payments (Rust) +│ └── doc_api/ # Documentation API +├── projects/lecoffre/ # Projet LeCoffre (notaires) +│ ├── lecoffre_node/ # Docker de contrôle +│ ├── lecoffre-front/ # Frontend Next.js +│ └── lecoffre-back-mini/ # Backend centralisé +├── IA_agents/ # Agents IA et documentation +├── docs/ # Documentation centralisée +├── scripts/ # Scripts de gestion centralisés +└── confs/ # Configurations déployées (4NK_vault) +``` + +## 🔧 Modules 4NK - Analyse Approfondie + +### 1. **sdk_relay** - Service de Relais WebSocket Central +**Rôle** : Relais central pour les communications WebSocket et la synchronisation mesh +- **Technologie** : Rust (tokio, async-trait, futures-util) +- **Ports** : 8090 (WebSocket), 8091 (HTTP health) +- **Dépendances** : + - `sdk_common` (git: https://git.4nkweb.com/4nk/sdk_common.git) + - `bitcoincore-rpc` (0.18) - Interface Bitcoin Core + - `tokio-tungstenite` (0.21.0) - WebSocket + - `zeromq` (0.4.1) - ZMQ Bitcoin Core +- **Fonctionnalités** : + - Serveur WebSocket configurable + - Synchronisation mesh entre relais + - Gestion des processus et membres + - Interface avec Bitcoin Core (RPC + ZMQ) + - Intégration Blindbit pour Silent Payments + - Cache de déduplication + - Gestion d'état locale dans `~/` +- **Architecture** : Rust avec gestion d'état locale +- **Configuration** : Fichier de configuration via `--config` +- **Healthcheck** : `/health` sur port 8091 + +### 2. **sdk_storage** - Service de Stockage Temporaire Sécurisé +**Rôle** : Stockage temporaire avec TTL et chiffrement +- **Technologie** : Rust (tide, async-std) +- **Port** : 8081 (mappé depuis 8080) +- **API** : + - `POST /store` : Stockage avec clé/valeur/TTL + - `GET /retrieve/:key` : Récupération des données +- **Fonctionnalités** : + - Stockage temporaire avec expiration + - Clés hexadécimales 64 caractères + - Valeurs hexadécimales + - TTL optionnel (permanent si non spécifié) + - Chiffrement des données +- **Architecture** : Rust avec async-std +- **Healthcheck** : `/health` sur port 8080 + +### 3. **sdk_signer** - Service de Signature TypeScript +**Rôle** : Service de signature pour l'écosystème 4NK +- **Technologie** : TypeScript avec support WASM +- **Fonctionnalités** : + - Gestion des processus et signatures + - Communication sécurisée + - Compatibilité WASM (stub temporaire) + - Interface avec le réseau de relais + - Validation des permissions +- **Architecture** : TypeScript avec support WASM +- **État** : Compatible avec stub sdk_client +- **Dépendances** : Node.js 18+, npm/yarn + +### 4. **sdk_client** - Client SDK Rust/WASM +**Rôle** : Client SDK pour l'interaction avec l'écosystème 4NK +- **Technologie** : Rust avec interface WebAssembly +- **Fonctionnalités** : + - Interface avec les services 4NK + - Gestion des connexions WebSocket + - Support des processus et transactions + - Compilation WASM pour le web +- **Architecture** : Rust avec interface WASM +- **Usage** : Importé par sdk_signer et autres clients + +### 5. **sdk_common** - Bibliothèque Commune +**Rôle** : Composants communs partagés entre tous les modules +- **Technologie** : Rust +- **Fonctionnalités** : + - Types et structures communes + - Utilitaires partagés + - Protocoles de communication + - Support Blindbit (feature: "blindbit-backend") + - Support parallèle (feature: "parallel") +- **Usage** : Importé par tous les autres modules +- **Features** : parallel, blindbit-backend + +### 6. **sdk-signer-client** - Client Signeur +**Rôle** : Client pour l'interaction avec le service de signature +- **Technologie** : TypeScript +- **Fonctionnalités** : + - Interface avec sdk_signer + - Gestion des signatures + - Communication sécurisée +- **Architecture** : TypeScript client + +### 7. **ihm_client** - Interface Homme-Machine +**Rôle** : Interface utilisateur pour la gestion des clés et processus +- **Technologie** : Vite + React +- **Port** : 3003 +- **Fonctionnalités** : + - Interface de gestion des clés Bitcoin + - Gestion des processus + - Interface utilisateur web + - Variables d'environnement Vite +- **Dépendances** : sdk_relay, sdk_storage +- **Variables** : VITE_JWT_SECRET_KEY, VITE_API_BASE_URL, VITE_WS_URL, VITE_STORAGE_URL, VITE_SIGNER_URL, VITE_BOOTSTRAPURL + +### 8. **4NK_vault** - Système de Gestion des Configurations +**Rôle** : API sécurisée pour la gestion centralisée des configurations +- **Technologie** : Python Flask +- **Port** : 6666 (HTTPS) +- **Sécurité** : + - Authentification par clés utilisateur + - Chiffrement quantique résistant (ChaCha20-Poly1305) + - Rotation automatique des clés (toutes les heures) + - Isolation par environnement (dev, prod) +- **Fonctionnalités** : + - Résolution des variables d'environnement + - Synchronisation vers `confs/` dans le docker de contrôle + - Protection des secrets + - Clés individuelles par utilisateur/environnement +- **Endpoints** : + - `GET /health` - Contrôle de santé + - `GET /info` - Informations API + - `GET /routes` - Routes disponibles + - `GET //` - Fichier chiffré +- **Déploiement** : Synchronise les configurations vers `confs/` + +### 9. **4NK_certificator** - Service d'Ancrage Cryptographique +**Rôle** : Ancrage périodique sur Bitcoin mainnet des empreintes des échanges +- **Technologie** : Rust +- **Fonctionnalités** : + - Surveillance des messages du relay 4NK + - Détection des paiements Bitcoin + - Enregistrement périodique sur blockchain + - Métriques de volume de données + - Base de données SQLite +- **Architecture** : Rust avec base de données SQLite +- **État** : MVP complet implémenté +- **Composants** : + - RelayMonitor (surveillance WebSocket) + - PaymentWatcher (surveillance Bitcoin) + - Base de données SQLite + +### 10. **4NK_miner** - Service de Minage +**Rôle** : Service de minage Bitcoin (développement/test) +- **Technologie** : Rust +- **Fonctionnalités** : + - Minage sur réseau Signet + - Génération de blocs de test + - Interface avec le réseau Bitcoin +- **Usage** : Développement et tests uniquement + +### 11. **4NK_web_status** - Service de Statut +**Rôle** : Service de monitoring et statut des services +- **Technologie** : Python Flask +- **Port** : 3006 +- **Fonctionnalités** : + - Monitoring des services + - Interface de statut + - Métriques de santé + - API REST pour le statut +- **Dépendances** : Docker socket, logs directory + +### 12. **blindbit-oracle** - Oracle Bitcoin Silent Payments +**Rôle** : Service pour les paiements silencieux (Silent Payments) +- **Technologie** : Rust +- **Port** : 8000 +- **Fonctionnalités** : + - Génération d'adresses Silent Payments + - Validation des transactions + - Interface HTTP REST + - Scan filtré BIP158 +- **Dépendances** : Bitcoin Core +- **Configuration** : blindbit.toml + +### 13. **rust-silentpayments** - Implémentation Silent Payments +**Rôle** : Implémentation Rust des Silent Payments +- **Technologie** : Rust +- **Fonctionnalités** : + - Génération d'adresses Silent Payments + - Validation des transactions + - Utilitaires cryptographiques +- **Usage** : Bibliothèque pour blindbit-oracle + +## 🏢 Projet LeCoffre - Architecture Notariale Détaillée + +### Contexte Métier +Le projet LeCoffre est une plateforme de gestion de documents sécurisée pour les notaires, utilisant l'infrastructure 4NK pour la sécurité et l'intégrité des documents. + +### Composants du Projet LeCoffre + +#### 1. **lecoffre_node** - Orchestrateur Principal +**Rôle** : Docker de contrôle et déploiement pour LeCoffre +- **Architecture** : Docker Compose avec Nginx intégré +- **Services déployés** : + - **tor** (btcpayserver/tor:0.4.8.10) - Proxy anonyme + - **bitcoin** (build: ./bitcoin) - Nœud Bitcoin Signet + - **blindbit** (git.4nkweb.com/4nk/blindbit-oracle:fixed-source) - Oracle Bitcoin + - **sdk_relay** (git.4nkweb.com/4nk/sdk_relay:ext) - Relais WebSocket + - **sdk_storage** (git.4nkweb.com/4nk/sdk_storage:ext) - Stockage temporaire + - **lecoffre-front** (git.4nkweb.com/4nk/lecoffre-front:ext) - Frontend Next.js + - **ihm_client** (git.4nkweb.com/4nk/ihm_client:ext) - Interface utilisateur + - **grafana** (grafana/grafana:latest) - Monitoring + - **loki** (grafana/loki:latest) - Collecte de logs + - **promtail** (grafana/promtail:latest) - Agent de collecte + - **status-api** (build: 4NK_web_status) - API de statut + - **watchtower** (containrrr/watchtower) - Mise à jour automatique + - **signet_miner** (build: 4NK_miner) - Minage (profile: miner) +- **Configuration** : Centralisée dans `confs/` (synchronisée depuis 4NK_vault) +- **Déploiement** : Scripts automatisés avec phases de démarrage +- **Réseau** : btcnet (172.20.0.0/16) +- **Volumes** : Persistance des données (bitcoin_data, blindbit_data, sdk_data, etc.) + +#### 2. **lecoffre-front** - Interface Utilisateur +**Rôle** : Frontend Next.js pour l'application LeCoffre +- **Technologie** : Next.js avec React +- **Port** : 3004 (mappé depuis 8080) +- **Fonctionnalités** : + - Interface utilisateur pour les notaires + - Gestion des documents + - Intégration avec l'écosystème 4NK + - Variables d'environnement Next.js +- **Variables** : NEXT_PUBLIC_API_URL, NEXT_PUBLIC_4NK_URL, NEXT_PUBLIC_4NK_IFRAME_URL, NEXT_PUBLIC_IDNOT_BASE_URL +- **Déploiement** : Conteneur Docker sur port 3004 +- **User** : lecoffreuser (non-root) + +#### 3. **lecoffre-back-mini** - Backend Centralisé +**Rôle** : Backend centralisé pour les besoins spécifiques des notaires +- **Déploiement** : Sur dev3.4nkweb.com +- **Fonctionnalités** : + - APIs avec Stripe (paiements) + - Intégration Mailchimp (email marketing) + - Intégration OVH (SMS) + - Intégration IdNot (HMR dev3 ↔ dev4 via OAuth2) +- **Architecture** : Service centralisé indépendant +- **APIs** : + - `/api/v1/health` - Santé du service + - `/api/v1/status` - Statut du service + - `/api/v1/idnot/state` - État IdNot + +## 🌐 Architecture de Déploiement Détaillée + +### Environnements et URLs +- **dev4.4nkweb.com** : Machine principale (LeCoffre) +- **dev3.4nkweb.com** : Nœud de bootstrap (signer centralisé, mini back) + +### URLs et Services +- **LeCoffre Front** : https://dev4.4nkweb.com/lecoffre +- **4NK iframe** : https://dev4.4nkweb.com +- **Signer centralisé** : dev3.4nkweb.com (module 4NK pour notaires) +- **Mini back** : dev3.4nkweb.com (APIs Stripe, Mailchimp, OVH, IdNot) + +### Architecture de Déploiement par Phases + +#### Phase 1: Services de Base (Parallèle) +- **tor** : Proxy anonyme (btcpayserver/tor:0.4.8.10) +- **sdk_storage** : Stockage temporaire (git.4nkweb.com/4nk/sdk_storage:ext) +- **status-api** : API de statut (build: 4NK_web_status) + +#### Phase 2: Services Blockchain (Séquentiel) +- **bitcoin** → **blindbit** → **sdk_relay** +- Chaîne de dépendances blockchain respectée + +#### Phase 3: Services Applicatifs (Séquentiel) +- **lecoffre-front** : Frontend Next.js +- **ihm_client** : Interface utilisateur +- Dépendances : sdk_relay + sdk_storage + +#### Phase 4: Services de Monitoring (Indépendant) +- **loki** → **promtail** → **grafana** +- Chaîne de dépendances monitoring + +#### Phase 5: Services Utilitaires +- **watchtower** : Mise à jour automatique (interval: 30s) + +## 🔐 Sécurité et Configuration Détaillée + +### 4NK_vault - Gestion Centralisée des Configurations +- **Rôle** : API sécurisée pour la gestion des configurations +- **Sécurité** : + - Chiffrement quantique résistant (ChaCha20-Poly1305) + - Authentification par clés utilisateur + - Rotation automatique des clés (toutes les heures) + - Isolation par environnement (dev, prod) +- **Déploiement** : Synchronise vers `confs/` dans le docker de contrôle +- **Protection des secrets** : Fichiers .env inaccessibles, variables séparées + +### 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é Détaillée + +### Stack de Monitoring +- **Grafana** (grafana/grafana:latest) : Dashboards et visualisation +- **Loki** (grafana/loki:latest) : Collecte et stockage des logs +- **Promtail** (grafana/promtail:latest) : Agent de collecte des logs +- **Watchtower** (containrrr/watchtower) : Mise à jour automatique + +### 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`) + +### 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 + +## 🔄 CI/CD et Déploiement Détaillé + +### Branches et Tags +- **Branche unifiée** : `ext` pour tous les dépôts 4NK +- **Branches spéciales** : `main` pour 4NK_certificator, 4NK_miner, 4NK_web_status +- **Tag Docker** : `ext` pour toutes les images +- **Déclenchement** : Push sur `ext` → Build automatique + +### Scripts de Déploiement Détaillés +- **start.sh** : Démarrage complet avec phases et progression +- **validate-deployment.sh** : Validation complète du déploiement +- **maintenance.sh** : Menu de maintenance interactif +- **backup-data.sh** : Sauvegarde des données +- **update-images.sh** : Mise à jour sécurisée +- **collect-logs.sh** : Collecte des logs +- **deploy-grafana.sh** : Déploiement du monitoring +- **sync-configs.sh** : Synchronisation des configurations + +### Healthchecks Détaillés +- **tor** : tor-progress.sh (bootstrap %) +- **bitcoin** : bitcoin-progress.sh (IBD, blocks, headers) +- **blindbit** : blindbit-progress.sh (API, scan) +- **sdk_relay** : sdk-relay-progress.sh (WebSocket, health) +- **sdk_storage** : curl /health +- **lecoffre-front** : ps aux | grep next-server +- **ihm_client** : curl localhost:3003 +- **grafana** : curl /api/health +- **loki** : wget /ready +- **promtail** : fichier positions.yaml +- **status-api** : curl /api + +## 🎯 Points Clés de l'Architecture Approfondie + +### 1. **Séparation des Responsabilités** +- Services applicatifs indépendants du monitoring +- Monitoring observant sans impacter +- Dépendances uniquement métier + +### 2. **Sécurité Multi-Niveaux** +- 4NK_vault pour la gestion centralisée des configurations +- Chiffrement quantique résistant +- Isolation des secrets et variables +- Utilisateurs non-root dans les conteneurs + +### 3. **Déploiement Optimisé** +- Phases de démarrage respectées +- Scripts spécialisés obligatoires +- Surveillance continue et diagnostic facilité +- Healthchecks informatifs + +### 4. **Maintenance Facilitée** +- Redémarrage sélectif possible +- Scripts de maintenance interactifs +- Documentation centralisée et à jour +- Logs centralisés et structurés + +### 5. **Architecture Modulaire** +- 13 modules 4NK avec rôles spécialisés +- Projet LeCoffre : Interface notariale +- 4NK_vault : Gestion centralisée des configurations +- Scripts centralisés et réutilisables + +--- + +**Document créé le 2025-01-27** +**Version** : 2.0 +**Usage** : Analyse architecturale approfondie pour les agents IA et l'équipe de développement diff --git a/docs/DEPLOYMENT_GUIDE.md b/docs/DEPLOYMENT_GUIDE.md new file mode 100644 index 0000000..771e143 --- /dev/null +++ b/docs/DEPLOYMENT_GUIDE.md @@ -0,0 +1,330 @@ +# 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 +``` + +#### 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 +``` + +## 📝 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 diff --git a/docs/DOCUMENTATION_SYNTHESIS.md b/docs/DOCUMENTATION_SYNTHESIS.md new file mode 100644 index 0000000..b05e893 --- /dev/null +++ b/docs/DOCUMENTATION_SYNTHESIS.md @@ -0,0 +1,217 @@ +# Synthèse de la Documentation - 4NK Environment + +**Date** : 2025-01-27 +**Version** : 2.0 +**Contexte** : Synthèse de toute la documentation mise à jour + +## 📋 Vue d'ensemble de la Documentation + +Cette synthèse présente l'organisation complète de la documentation mise à jour pour l'environnement 4NK, incluant tous les documents créés et mis à jour. + +## 📚 Structure de la Documentation + +### Documentation Principale (docs/) +1. **DEEP_ARCHITECTURE_ANALYSIS.md** - Analyse architecturale approfondie complète +2. **TECHNICAL_REFERENCE.md** - Référence technique complète +3. **DEPLOYMENT_GUIDE.md** - Guide de déploiement complet +4. **ARCHITECTURE_ANALYSIS.md** - Analyse architecturale complète 4NK + LeCoffre +5. **context.md** - Contexte général des projets 4NK et LeCoffre +6. **flux.md** - Architecture des flux et services + +### Documentation des Agents IA (IA_agents/) +1. **AGENTS_SYNTHESIS.md** - Synthèse complète pour les agents IA +2. **README.md** - Documentation principale et règles obligatoires +3. **deployment-architecture.md** - Architecture de déploiement par phases +4. **best-practices-deployment.md** - Bonnes pratiques et interdictions +5. **todo.md** - Liste des tâches et améliorations à suivre + +### Documentation du Projet (README.md) +- **README.md** - Documentation principale mise à jour +- **Documentation centralisée** - Tous les documents référencés +- **Liens cohérents** - Navigation facilitée + +## 🔧 Modules 4NK - Documentation Complète + +### 13 Modules Documentés +1. **sdk_relay** - Service de Relais WebSocket Central +2. **sdk_storage** - Service de Stockage Temporaire Sécurisé +3. **sdk_signer** - Service de Signature TypeScript +4. **sdk_client** - Client SDK Rust/WASM +5. **sdk_common** - Bibliothèque Commune +6. **sdk-signer-client** - Client Signeur +7. **ihm_client** - Interface Homme-Machine +8. **4NK_vault** - Système de Gestion des Configurations +9. **4NK_certificator** - Service d'Ancrage Cryptographique +10. **4NK_miner** - Service de Minage +11. **4NK_web_status** - Service de Statut +12. **blindbit-oracle** - Oracle Bitcoin Silent Payments +13. **rust-silentpayments** - Implémentation Silent Payments + +### Documentation Technique par Module +- **Technologie** : Rust, TypeScript, Python +- **Ports** : Tous les ports documentés +- **Dépendances** : Dépendances Rust, Node.js, Python +- **Fonctionnalités** : Toutes les fonctionnalités détaillées +- **Configuration** : Variables d'environnement et fichiers de config +- **Healthchecks** : Tous les healthchecks documentés + +## 🏢 Projet LeCoffre - Documentation Complète + +### 3 Composants Documentés +1. **lecoffre_node** - Orchestrateur Principal +2. **lecoffre-front** - Interface Utilisateur +3. **lecoffre-back-mini** - Backend Centralisé + +### Documentation par Composant +- **Architecture** : Docker Compose avec Nginx intégré +- **Services** : Tous les services déployés +- **Configuration** : Centralisée dans `confs/` +- **Déploiement** : Scripts automatisés avec phases +- **Variables** : Toutes les variables d'environnement +- **URLs** : Toutes les URLs et services + +## 🌐 Architecture de Déploiement - Documentation Complète + +### 5 Phases Documentées +1. **Phase 1** : Services de Base (Parallèle) +2. **Phase 2** : Services Blockchain (Séquentiel) +3. **Phase 3** : Services Applicatifs (Séquentiel) +4. **Phase 4** : Services de Monitoring (Indépendant) +5. **Phase 5** : Services Utilitaires + +### Scripts Documentés +- **Scripts OBLIGATOIRES** : start.sh, start-monitoring.sh, validate-deployment.sh +- **Scripts INTERDITS** : docker compose up -d (toute variante) +- **Fonctionnalités** : Toutes les fonctionnalités des scripts +- **Utilisation** : Guide d'utilisation complet + +## 🔐 Sécurité et Configuration - Documentation Complète + +### 4NK_vault Documenté +- **Rôle** : API sécurisée pour la gestion des configurations +- **Sécurité** : Chiffrement quantique résistant, authentification +- **Déploiement** : Synchronisation vers `confs/` +- **Protection** : Fichiers .env inaccessibles, variables séparées + +### Variables d'Environnement Documentées +- **Par service** : Toutes les variables par service +- **Critiques** : Variables critiques identifiées +- **Validation** : Scripts de validation des variables +- **Synchronisation** : Processus de synchronisation + +## 📊 Monitoring et Observabilité - Documentation Complète + +### Stack de Monitoring Documenté +- **Grafana** : Dashboards et visualisation +- **Loki** : Collecte et stockage des logs +- **Promtail** : Agent de collecte des logs +- **Watchtower** : Mise à jour automatique + +### Configuration Critique Documentée +- **Loki** : Configuration critique documentée +- **Dashboards** : Tous les dashboards documentés +- **Logs** : Centralisation et collecte documentées + +## 🔄 CI/CD et Déploiement - Documentation Complète + +### Branches et Tags Documentés +- **Branche unifiée** : `ext` pour tous les dépôts 4NK +- **Branches spéciales** : `main` pour certains modules +- **Tag Docker** : `ext` pour toutes les images +- **Déclenchement** : Processus de déclenchement documenté + +### Scripts de Déploiement Documentés +- **Démarrage** : Scripts de démarrage complets +- **Validation** : Scripts de validation complets +- **Maintenance** : Scripts de maintenance complets +- **Healthchecks** : Tous les healthchecks documentés + +## 🎯 Points Clés de la Documentation + +### 1. **Cohérence Complète** +- Tous les modules documentés +- Toutes les configurations documentées +- Tous les scripts documentés +- Toutes les variables documentées + +### 2. **Navigation Facilitée** +- Liens cohérents entre documents +- Structure hiérarchique claire +- Références croisées complètes +- Index et tables des matières + +### 3. **Utilisation Optimisée** +- Guides de déploiement complets +- Références techniques détaillées +- Bonnes pratiques documentées +- Dépannage et maintenance + +### 4. **Mise à Jour Continue** +- Documentation centralisée +- Synchronisation avec le code +- Validation de cohérence +- Amélioration continue + +## 📝 Validation de la Documentation + +### Documents Créés +- **DEEP_ARCHITECTURE_ANALYSIS.md** : Analyse architecturale approfondie +- **TECHNICAL_REFERENCE.md** : Référence technique complète +- **DEPLOYMENT_GUIDE.md** : Guide de déploiement complet +- **DOCUMENTATION_SYNTHESIS.md** : Synthèse de la documentation + +### Documents Mis à Jour +- **README.md** : Documentation principale +- **IA_agents/README.md** : Documentation des agents IA +- **IA_agents/AGENTS_SYNTHESIS.md** : Synthèse pour les agents IA + +### Cohérence Vérifiée +- **Liens** : Tous les liens fonctionnels +- **Références** : Toutes les références cohérentes +- **Structure** : Structure hiérarchique respectée +- **Contenu** : Contenu complet et détaillé + +## 🚀 Utilisation de la Documentation + +### Pour les Agents IA +1. **Commencer par** : `IA_agents/AGENTS_SYNTHESIS.md` +2. **Analyser** : `docs/DEEP_ARCHITECTURE_ANALYSIS.md` +3. **Référencer** : `docs/TECHNICAL_REFERENCE.md` +4. **Déployer** : `docs/DEPLOYMENT_GUIDE.md` + +### Pour les Développeurs +1. **Commencer par** : `README.md` +2. **Analyser** : `docs/ARCHITECTURE_ANALYSIS.md` +3. **Référencer** : `docs/TECHNICAL_REFERENCE.md` +4. **Déployer** : `docs/DEPLOYMENT_GUIDE.md` + +### Pour l'Équipe +1. **Commencer par** : `docs/DOCUMENTATION_SYNTHESIS.md` +2. **Analyser** : `docs/DEEP_ARCHITECTURE_ANALYSIS.md` +3. **Référencer** : `docs/TECHNICAL_REFERENCE.md` +4. **Déployer** : `docs/DEPLOYMENT_GUIDE.md` + +## 📊 Métriques de la Documentation + +### Documents Créés +- **4 nouveaux documents** de documentation technique +- **3 documents mis à jour** avec analyse approfondie +- **1 synthèse complète** de la documentation + +### Couverture +- **13 modules 4NK** entièrement documentés +- **3 composants LeCoffre** entièrement documentés +- **5 phases de déploiement** entièrement documentées +- **Tous les scripts** entièrement documentés + +### Qualité +- **Cohérence** : Tous les liens et références cohérents +- **Complétude** : Tous les aspects couverts +- **Utilisabilité** : Navigation et utilisation optimisées +- **Maintenabilité** : Structure évolutive et maintenable + +--- + +**Document créé le 2025-01-27** +**Version** : 2.0 +**Usage** : Synthèse complète de la documentation mise à jour diff --git a/docs/README-URL-TESTS.md b/docs/README-URL-TESTS.md index ec46c8b..c04dd9f 100644 --- a/docs/README-URL-TESTS.md +++ b/docs/README-URL-TESTS.md @@ -49,23 +49,23 @@ cd /home/debian/4NK_env/scripts/lecoffre_node - Status API (`http://localhost:3006/api`) ### ✅ URLs Externes (Domaine Public) -- Site Principal (`https://dev4.4nkweb.com/`) -- Page de Statut (`https://dev4.4nkweb.com/status/`) -- Dashboard Grafana (`https://dev4.4nkweb.com/grafana/`) -- Application LeCoffre (`https://dev4.4nkweb.com/lecoffre/`) -- Login LeCoffre (`https://dev4.4nkweb.com/lecoffre/login`) -- Callback Auth (`https://dev4.4nkweb.com/lecoffre/authorized-client`) +- Site Principal (`/`) +- Page de Statut (`/status/`) +- Dashboard Grafana (`/grafana/`) +- Application LeCoffre (`/lecoffre/`) +- Login LeCoffre (`/lecoffre/login`) +- Callback Auth (`/lecoffre/authorized-client`) ### ✅ APIs Externes (Backend Services) -- API Backend Health (`https://dev3.4nkweb.com/api/v1/health`) -- API Backend Status (`https://dev3.4nkweb.com/api/v1/status`) -- IdNot State Endpoint (`https://dev3.4nkweb.com/api/v1/idnot/state`) +- API Backend Health (`/api/v1/health`) +- API Backend Status (`/api/v1/status`) +- IdNot State Endpoint (`/api/v1/idnot/state`) ### ✅ WebSockets Externes -- Bootstrap Relay (`wss://dev3.4nkweb.com/ws/`) +- Bootstrap Relay (`wss:///ws/`) ### ✅ Services Externes (Dépendances) -- Mempool Signet (`https://mempool2.4nkweb.com/`) +- Mempool Signet (``) - Service IdNot (`https://qual-connexion.idnot.fr/`) - IdNot Authorization (`https://qual-connexion.idnot.fr/IdPOAuth2/authorize/idnot_idp_v1`) @@ -118,7 +118,7 @@ cd /home/debian/4NK_env/scripts/lecoffre_node ### APIs Non Accessibles - Vérifier la configuration CORS -- Vérifier la connectivité vers dev3.4nkweb.com +- Vérifier la connectivité vers `` - Consulter les logs du backend ## 📚 Documentation Complète diff --git a/docs/TECHNICAL_REFERENCE.md b/docs/TECHNICAL_REFERENCE.md new file mode 100644 index 0000000..5b065ba --- /dev/null +++ b/docs/TECHNICAL_REFERENCE.md @@ -0,0 +1,406 @@ +# Référence Technique Complète - 4NK Environment + +**Date** : 2025-01-27 +**Version** : 2.0 +**Contexte** : Référence technique complète pour les développeurs et agents IA + +## 📋 Vue d'ensemble Technique + +Cette référence technique présente tous les détails techniques de l'environnement 4NK, incluant les configurations, dépendances, ports, et interfaces. + +## 🔧 Modules 4NK - Référence Technique Complète + +### 1. **sdk_relay** - Service de Relais WebSocket Central +**Technologie** : Rust (tokio, async-trait, futures-util) +**Ports** : 8090 (WebSocket), 8091 (HTTP health) +**Dépendances Rust** : +```toml +anyhow = "1.0" +async-trait = "0.1" +bitcoincore-rpc = { version = "0.18" } +env_logger = "0.9" +futures-util = { version = "0.3.28", default-features = false, features = ["sink", "std"] } +hex = "0.4.3" +log = "0.4.20" +sdk_common = { git = "https://git.4nkweb.com/4nk/sdk_common.git", rev = "e205229e", features = ["parallel", "blindbit-backend"] } +serde = { version = "1.0.193", features = ["derive"]} +serde_json = "1.0" +serde_with = "3.6.0" +tokio = { version = "1.0.0", features = ["io-util", "rt-multi-thread", "macros", "sync"] } +tokio-stream = "0.1" +tokio-tungstenite = "0.21.0" +zeromq = "0.4.1" +``` +**Fonctionnalités** : +- Serveur WebSocket configurable +- Synchronisation mesh entre relais +- Gestion des processus et membres +- Interface avec Bitcoin Core (RPC + ZMQ) +- Intégration Blindbit pour Silent Payments +- Cache de déduplication +- Gestion d'état locale dans `~/` +**Configuration** : Fichier de configuration via `--config` +**Healthcheck** : `/health` sur port 8091 +**Variables d'environnement** : RELAY_PORT, RELAY_HTTP_PORT, STORAGE_URL + +### 2. **sdk_storage** - Service de Stockage Temporaire Sécurisé +**Technologie** : Rust (tide, async-std) +**Port** : 8081 (mappé depuis 8080) +**Dépendances Rust** : +```toml +tide = "0.16" +async-std = { version = "1", features = ["attributes"] } +serde = { version = "1", features = ["derive"] } +serde_json = "1" +hex = "0.4" +env_logger = "0.10" +``` +**API** : +- `POST /store` : Stockage avec clé/valeur/TTL +- `GET /retrieve/:key` : Récupération des données +**Fonctionnalités** : +- Stockage temporaire avec expiration +- Clés hexadécimales 64 caractères +- Valeurs hexadécimales +- TTL optionnel (permanent si non spécifié) +- Chiffrement des données +**Healthcheck** : `/health` sur port 8080 +**Variables d'environnement** : STORAGE_PORT, STORAGE_DATA_DIR + +### 3. **sdk_signer** - Service de Signature TypeScript +**Technologie** : TypeScript avec support WASM +**Fonctionnalités** : +- Gestion des processus et signatures +- Communication sécurisée +- Compatibilité WASM (stub temporaire) +- Interface avec le réseau de relais +- Validation des permissions +**Dépendances** : Node.js 18+, npm/yarn +**Architecture** : TypeScript avec support WASM +**État** : Compatible avec stub sdk_client + +### 4. **sdk_client** - Client SDK Rust/WASM +**Technologie** : Rust avec interface WebAssembly +**Fonctionnalités** : +- Interface avec les services 4NK +- Gestion des connexions WebSocket +- Support des processus et transactions +- Compilation WASM pour le web +**Architecture** : Rust avec interface WASM +**Usage** : Importé par sdk_signer et autres clients + +### 5. **sdk_common** - Bibliothèque Commune +**Technologie** : Rust +**Fonctionnalités** : +- Types et structures communes +- Utilitaires partagés +- Protocoles de communication +- Support Blindbit (feature: "blindbit-backend") +- Support parallèle (feature: "parallel") +**Usage** : Importé par tous les autres modules +**Features** : parallel, blindbit-backend + +### 6. **sdk-signer-client** - Client Signeur +**Technologie** : TypeScript +**Fonctionnalités** : +- Interface avec sdk_signer +- Gestion des signatures +- Communication sécurisée +**Architecture** : TypeScript client + +### 7. **ihm_client** - Interface Homme-Machine +**Technologie** : Vite + React +**Port** : 3003 +**Fonctionnalités** : +- Interface de gestion des clés Bitcoin +- Gestion des processus +- Interface utilisateur web +- Variables d'environnement Vite +**Dépendances** : sdk_relay, sdk_storage +**Variables d'environnement** : +- VITE_JWT_SECRET_KEY +- VITE_API_BASE_URL +- VITE_WS_URL +- VITE_STORAGE_URL +- VITE_SIGNER_URL +- VITE_BOOTSTRAPURL + +### 8. **4NK_vault** - Système de Gestion des Configurations +**Technologie** : Python Flask +**Port** : 6666 (HTTPS) +**Sécurité** : +- Authentification par clés utilisateur +- Chiffrement quantique résistant (ChaCha20-Poly1305) +- Rotation automatique des clés (toutes les heures) +- Isolation par environnement (dev, prod) +**Fonctionnalités** : +- Résolution des variables d'environnement +- Synchronisation vers `confs/` dans le docker de contrôle +- Protection des secrets +- Clés individuelles par utilisateur/environnement +**Endpoints** : +- `GET /health` - Contrôle de santé +- `GET /info` - Informations API +- `GET /routes` - Routes disponibles +- `GET //` - Fichier chiffré +**Déploiement** : Synchronise les configurations vers `confs/` + +### 9. **4NK_certificator** - Service d'Ancrage Cryptographique +**Technologie** : Rust +**Fonctionnalités** : +- Surveillance des messages du relay 4NK +- Détection des paiements Bitcoin +- Enregistrement périodique sur blockchain +- Métriques de volume de données +- Base de données SQLite +**Architecture** : Rust avec base de données SQLite +**État** : MVP complet implémenté +**Composants** : +- RelayMonitor (surveillance WebSocket) +- PaymentWatcher (surveillance Bitcoin) +- Base de données SQLite + +### 10. **4NK_miner** - Service de Minage +**Technologie** : Rust +**Fonctionnalités** : +- Minage sur réseau Signet +- Génération de blocs de test +- Interface avec le réseau Bitcoin +**Usage** : Développement et tests uniquement + +### 11. **4NK_web_status** - Service de Statut +**Technologie** : Python Flask +**Port** : 3006 +**Fonctionnalités** : +- Monitoring des services +- Interface de statut +- Métriques de santé +- API REST pour le statut +**Dépendances** : Docker socket, logs directory +**Variables d'environnement** : STATUS_API_PORT, STATUS_API_HOST + +### 12. **blindbit-oracle** - Oracle Bitcoin Silent Payments +**Technologie** : Rust +**Port** : 8000 +**Fonctionnalités** : +- Génération d'adresses Silent Payments +- Validation des transactions +- Interface HTTP REST +- Scan filtré BIP158 +**Dépendances** : Bitcoin Core +**Configuration** : blindbit.toml +**Variables d'environnement** : BLINDBIT_API_PORT, BITCOIN_RPC_URL + +### 13. **rust-silentpayments** - Implémentation Silent Payments +**Technologie** : Rust +**Fonctionnalités** : +- Génération d'adresses Silent Payments +- Validation des transactions +- Utilitaires cryptographiques +**Usage** : Bibliothèque pour blindbit-oracle + +## 🏢 Projet LeCoffre - Référence Technique Complète + +### 1. **lecoffre_node** - Orchestrateur Principal +**Architecture** : Docker Compose avec Nginx intégré +**Services déployés** : +- **tor** (btcpayserver/tor:0.4.8.10) - Proxy anonyme +- **bitcoin** (build: ./bitcoin) - Nœud Bitcoin Signet +- **blindbit** (git.4nkweb.com/4nk/blindbit-oracle:fixed-source) - Oracle Bitcoin +- **sdk_relay** (git.4nkweb.com/4nk/sdk_relay:ext) - Relais WebSocket +- **sdk_storage** (git.4nkweb.com/4nk/sdk_storage:ext) - Stockage temporaire +- **lecoffre-front** (git.4nkweb.com/4nk/lecoffre-front:ext) - Frontend Next.js +- **ihm_client** (git.4nkweb.com/4nk/ihm_client:ext) - Interface utilisateur +- **grafana** (grafana/grafana:latest) - Monitoring +- **loki** (grafana/loki:latest) - Collecte de logs +- **promtail** (grafana/promtail:latest) - Agent de collecte +- **status-api** (build: 4NK_web_status) - API de statut +- **watchtower** (containrrr/watchtower) - Mise à jour automatique +- **signet_miner** (build: 4NK_miner) - Minage (profile: miner) + +**Configuration** : Centralisée dans `confs/` (synchronisée depuis 4NK_vault) +**Déploiement** : Scripts automatisés avec phases de démarrage +**Réseau** : btcnet (172.20.0.0/16) +**Volumes** : Persistance des données (bitcoin_data, blindbit_data, sdk_data, etc.) + +### 2. **lecoffre-front** - Interface Utilisateur +**Technologie** : Next.js avec React +**Port** : 3004 (mappé depuis 8080) +**Fonctionnalités** : +- Interface utilisateur pour les notaires +- Gestion des documents +- Intégration avec l'écosystème 4NK +- Variables d'environnement Next.js +**Variables d'environnement** : +- NEXT_PUBLIC_API_URL +- NEXT_PUBLIC_4NK_URL +- NEXT_PUBLIC_4NK_IFRAME_URL +- NEXT_PUBLIC_IDNOT_BASE_URL +**Déploiement** : Conteneur Docker sur port 3004 +**User** : lecoffreuser (non-root) + +### 3. **lecoffre-back-mini** - Backend Centralisé +**Déploiement** : Sur dev3.4nkweb.com +**Fonctionnalités** : +- APIs avec Stripe (paiements) +- Intégration Mailchimp (email marketing) +- Intégration OVH (SMS) +- Intégration IdNot (HMR dev3 ↔ dev4 via OAuth2) +**Architecture** : Service centralisé indépendant +**APIs** : +- `/api/v1/health` - Santé du service +- `/api/v1/status` - Statut du service +- `/api/v1/idnot/state` - État IdNot + +## 🌐 Architecture de Déploiement - Référence Technique + +### Environnements et URLs +- **dev4.4nkweb.com** : Machine principale (LeCoffre) +- **dev3.4nkweb.com** : Nœud de bootstrap (signer centralisé, mini back) + +### URLs et Services +- **LeCoffre Front** : https://dev4.4nkweb.com/lecoffre +- **4NK iframe** : https://dev4.4nkweb.com +- **Signer centralisé** : dev3.4nkweb.com (module 4NK pour notaires) +- **Mini back** : dev3.4nkweb.com (APIs Stripe, Mailchimp, OVH, IdNot) + +### Architecture de Déploiement par Phases + +#### Phase 1: Services de Base (Parallèle) +- **tor** : Proxy anonyme (btcpayserver/tor:0.4.8.10) +- **sdk_storage** : Stockage temporaire (git.4nkweb.com/4nk/sdk_storage:ext) +- **status-api** : API de statut (build: 4NK_web_status) + +#### Phase 2: Services Blockchain (Séquentiel) +- **bitcoin** → **blindbit** → **sdk_relay** +- Chaîne de dépendances blockchain respectée + +#### Phase 3: Services Applicatifs (Séquentiel) +- **lecoffre-front** : Frontend Next.js +- **ihm_client** : Interface utilisateur +- Dépendances : sdk_relay + sdk_storage + +#### Phase 4: Services de Monitoring (Indépendant) +- **loki** → **promtail** → **grafana** +- Chaîne de dépendances monitoring + +#### Phase 5: Services Utilitaires +- **watchtower** : Mise à jour automatique (interval: 30s) + +## 🔐 Sécurité et Configuration - Référence Technique + +### 4NK_vault - Gestion Centralisée des Configurations +- **Rôle** : API sécurisée pour la gestion des configurations +- **Sécurité** : + - Chiffrement quantique résistant (ChaCha20-Poly1305) + - Authentification par clés utilisateur + - Rotation automatique des clés (toutes les heures) + - Isolation par environnement (dev, prod) +- **Déploiement** : Synchronise vers `confs/` dans le docker de contrôle +- **Protection des secrets** : Fichiers .env inaccessibles, variables séparées + +### 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é - Référence Technique + +### Stack de Monitoring +- **Grafana** (grafana/grafana:latest) : Dashboards et visualisation +- **Loki** (grafana/loki:latest) : Collecte et stockage des logs +- **Promtail** (grafana/promtail:latest) : Agent de collecte des logs +- **Watchtower** (containrrr/watchtower) : Mise à jour automatique + +### 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`) + +### 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 + +## 🔄 CI/CD et Déploiement - Référence Technique + +### Branches et Tags +- **Branche unifiée** : `ext` pour tous les dépôts 4NK +- **Branches spéciales** : `main` pour 4NK_certificator, 4NK_miner, 4NK_web_status +- **Tag Docker** : `ext` pour toutes les images +- **Déclenchement** : Push sur `ext` → Build automatique + +### Scripts de Déploiement Détaillés +- **start.sh** : Démarrage complet avec phases et progression +- **validate-deployment.sh** : Validation complète du déploiement +- **maintenance.sh** : Menu de maintenance interactif +- **backup-data.sh** : Sauvegarde des données +- **update-images.sh** : Mise à jour sécurisée +- **collect-logs.sh** : Collecte des logs +- **deploy-grafana.sh** : Déploiement du monitoring +- **sync-configs.sh** : Synchronisation des configurations + +### Healthchecks Détaillés +- **tor** : tor-progress.sh (bootstrap %) +- **bitcoin** : bitcoin-progress.sh (IBD, blocks, headers) +- **blindbit** : blindbit-progress.sh (API, scan) +- **sdk_relay** : sdk-relay-progress.sh (WebSocket, health) +- **sdk_storage** : curl /health +- **lecoffre-front** : ps aux | grep next-server +- **ihm_client** : curl localhost:3003 +- **grafana** : curl /api/health +- **loki** : wget /ready +- **promtail** : fichier positions.yaml +- **status-api** : curl /api + +## 🎯 Points Clés de l'Architecture Technique + +### 1. **Séparation des Responsabilités** +- Services applicatifs indépendants du monitoring +- Monitoring observant sans impacter +- Dépendances uniquement métier + +### 2. **Sécurité Multi-Niveaux** +- 4NK_vault pour la gestion centralisée des configurations +- Chiffrement quantique résistant +- Isolation des secrets et variables +- Utilisateurs non-root dans les conteneurs + +### 3. **Déploiement Optimisé** +- Phases de démarrage respectées +- Scripts spécialisés obligatoires +- Surveillance continue et diagnostic facilité +- Healthchecks informatifs + +### 4. **Maintenance Facilitée** +- Redémarrage sélectif possible +- Scripts de maintenance interactifs +- Documentation centralisée et à jour +- Logs centralisés et structurés + +### 5. **Architecture Modulaire** +- 13 modules 4NK avec rôles spécialisés +- Projet LeCoffre : Interface notariale +- 4NK_vault : Gestion centralisée des configurations +- Scripts centralisés et réutilisables + +--- + +**Document créé le 2025-01-27** +**Version** : 2.0 +**Usage** : Référence technique complète pour les développeurs et agents IA diff --git a/docs/flux.md b/docs/flux.md index 0d56361..c6b30f5 100644 --- a/docs/flux.md +++ b/docs/flux.md @@ -84,7 +84,7 @@ | **RELAY_URLS** | wss://dev4.4nkweb.com/ws/,wss://dev3.4nkweb.com/ws/ || | **bootstrap_url** | wss://dev3.4nkweb.com/ws/ | sdk_relay | | **storage** | https://dev4.4nkweb.com/storage | sdk_relay | -| **GRAFANA_ADMIN_PASSWORD** | admin123 | grafana | +| **GRAFANA_ADMIN_PASSWORD** | | grafana | | **GF_SERVER_ROOT_URL** | https://dev4.4nkweb.com/grafana/ | grafana | **Variables centralisées** : @@ -208,7 +208,7 @@ Selon les règles du projet, l'ordre de démarrage est : - **Test monitoring complet** : `./scripts/test-monitoring.sh` - **Déploiement Grafana** : `./scripts/deploy-grafana.sh start` - **Collecte des logs** : `./scripts/collect-logs.sh` -- **Grafana local** : `http://localhost:3005` (admin/admin123) +- **Grafana local** : `http://localhost:3005` (admin/) - **Loki API** : `http://localhost:3100/loki/api/v1/labels` - **Test connectivité Grafana** : `curl http://localhost:3005/api/health` - **Test connectivité Loki** : `curl http://localhost:3100/ready` diff --git a/projects/lecoffre/lecoffre-back-mini b/projects/lecoffre/lecoffre-back-mini new file mode 160000 index 0000000..ba2c36c --- /dev/null +++ b/projects/lecoffre/lecoffre-back-mini @@ -0,0 +1 @@ +Subproject commit ba2c36c0143fcf2b36c52903bd5dceec0cf42649