4NK_env/IA_agents/env-centralisation-policy.md

Politique de Centralisation des Variables d'Environnement

Vue d'ensemble

Ce document définit la politique de gestion des variables d'environnement pour le projet 4NK. La nouvelle architecture sépare les variables par projet tout en maintenant une approche centralisée et sécurisée.

Structure Actuelle (Depuis 2024-09-27)

Architecture Séparée par Projet

4NK_env/
├── env/
│   ├── lecoffre_node/.env      # Variables du nœud principal
│   ├── sdk_relay/.env          # Variables du service relay
│   ├── sdk_storage/.env        # Variables du service storage
│   ├── ihm_client/.env         # Variables de l'interface client
│   ├── lecoffre-front/.env     # Variables du frontend
│   ├── blindbit-oracle/.env    # Variables de l'oracle BlindBit
│   ├── monitoring/.env         # Variables de monitoring
│   └── sdk_signer/.env         # Variables du service signer
└── .env.master                 # Conservé pour compatibilité

Principes de Gestion

1. Séparation par Responsabilité

• Chaque service a ses propres variables d'environnement
• Isolation des configurations sensibles
• Réduction des risques de fuite de données

2. Conservation des Valeurs

• JAMAIS modifier les valeurs des variables existantes
• Toutes les valeurs du .env.master original sont préservées
• Seule la structure d'organisation change

3. Sécurité Renforcée

• Variables sensibles isolées par service
• Identification claire des données sensibles
• Préfixe FAKE-DATA-IA- pour les données de test

4. Compatibilité Maintenue

• Fichier .env.master conservé pour compatibilité
• Scripts mis à jour progressivement
• Migration transparente

Classification des Variables

Variables Sensibles (Critiques)

# ================== /!\ sensible =========================
IDNOT_API_KEY=...
IDNOT_CLIENT_SECRET=...
VITE_JWT_SECRET_KEY=...
SIGNER_API_KEY=...
GRAFANA_ADMIN_PASSWORD=...

Variables de Configuration (Importantes)

# Configuration des domaines et URLs
DOMAIN=dev4.4nkweb.com
API_BASE_URL=https://${DOMAIN}/api
STORAGE_URL=https://${DOMAIN}/storage

Variables de Développement (Optionnelles)

# Variables pour le développement et les tests
RUST_LOG=DEBUG
NODE_OPTIONS=--max-old-space-size=2048

Règles de Gestion

Règle 1: Ne Jamais Modifier les Valeurs

• Toutes les valeurs du .env.master original sont préservées
• Seule l'organisation en fichiers séparés est modifiée
• Validation obligatoire avant toute modification

Règle 2: Utiliser les Scripts Officiels

# Ajout de variables manquantes
./scripts/add-missing-env-vars-new.sh

# Test de configuration
./scripts/test-env-config.sh

# Démarrage des services
./scripts/lecoffre_node/start.sh

Règle 3: Documentation Obligatoire

• Toute nouvelle variable doit être documentée
• Mise à jour des fichiers de documentation
• Explication de l'utilisation et de la sensibilité

Règle 4: Test Avant Déploiement

• Validation de la configuration avec les scripts
• Test de démarrage des services
• Vérification de la cohérence des variables

Processus de Migration

Étape 1: Création de la Structure

mkdir -p /home/debian/4NK_env/env/{lecoffre_node,sdk_relay,sdk_storage,ihm_client,lecoffre-front,blindbit-oracle,monitoring,sdk_signer}

Étape 2: Séparation des Variables

• Analyse du .env.master original
• Répartition par projet selon l'utilisation
• Conservation de toutes les valeurs

Étape 3: Mise à Jour des Configurations

• Modification du docker-compose.yml
• Mise à jour des scripts de gestion
• Adaptation des fichiers de configuration

Étape 4: Tests et Validation

• Exécution des scripts de test
• Vérification du démarrage des services
• Validation de la cohérence

Étape 5: Documentation

• Création de la documentation de la nouvelle structure
• Mise à jour des guides existants
• Formation des équipes

Gestion des Variables par Projet

lecoffre_node

• Responsabilité: Configuration générale et nœud principal
• Variables clés: DOMAIN, GIT_TOKEN, IDNOT_*, API_BASE_URL
• Sensibilité: Élevée (tokens et clés API)

sdk_relay

• Responsabilité: Service de relay WebSocket
• Variables clés: SDK_RELAY_*, CORE_URL, WS_URL
• Sensibilité: Moyenne (configuration réseau)

sdk_storage

• Responsabilité: Service de stockage
• Variables clés: STORAGE_URL, STORAGE_PORT
• Sensibilité: Faible (configuration technique)

ihm_client

• Responsabilité: Interface utilisateur
• Variables clés: VITE_*, JWT_SECRET_KEY
• Sensibilité: Élevée (secret JWT)

lecoffre-front

• Responsabilité: Frontend Next.js
• Variables clés: NEXT_PUBLIC_*, IDNOT_CLIENT_ID
• Sensibilité: Moyenne (client ID)

blindbit-oracle

• Responsabilité: Oracle BlindBit
• Variables clés: BLINDBIT_API_PORT, BITCOIN_RPC_URL
• Sensibilité: Faible (configuration technique)

monitoring

• Responsabilité: Surveillance et logs
• Variables clés: GRAFANA_, LOKI_, STATUS_API_*
• Sensibilité: Moyenne (mots de passe admin)

sdk_signer

• Responsabilité: Service de signature
• Variables clés: SIGNER_*, API_KEY
• Sensibilité: Élevée (clé API de signature)

Scripts de Gestion

add-missing-env-vars-new.sh

• Ajoute les variables manquantes dans la nouvelle structure
• Crée des sauvegardes automatiques
• Validation des variables par projet

test-env-config.sh

• Teste la cohérence de la configuration
• Vérifie la présence des fichiers .env
• Valide le chargement des variables

start.sh (lecoffre_node)

• Démarre les services avec la nouvelle structure
• Vérifie les variables par service
• Gestion des erreurs et diagnostics

Sécurité

Bonnes Pratiques

1. Isolation: Chaque service n'accède qu'à ses variables
2. Sensibilité: Identification claire des données sensibles
3. Audit: Traçabilité des modifications
4. Sauvegarde: Sauvegarde automatique avant modifications

Variables Sensibles

• Utilisation du préfixe FAKE-DATA-IA- pour les données de test
• Section dédiée # ================== /!\ sensible =========================
• Documentation de la sensibilité dans les commentaires

Maintenance

Ajout d'un Nouveau Service

1. Créer le dossier env/<nouveau_service>/
2. Définir les variables nécessaires
3. Mettre à jour les scripts et configurations
4. Documenter dans ce fichier

Modification d'une Variable

1. Identifier le service concerné
2. Modifier uniquement le fichier correspondant
3. Tester la configuration
4. Mettre à jour la documentation

Suppression d'un Service

1. Sauvegarder le fichier .env
2. Supprimer le dossier du service
3. Mettre à jour les configurations
4. Nettoyer la documentation

Monitoring et Alertes

Variables Critiques à Surveiller

• IDNOT_API_KEY: Clé API IDNot
• VITE_JWT_SECRET_KEY: Secret JWT
• SIGNER_API_KEY: Clé API Signer
• GRAFANA_ADMIN_PASSWORD: Mot de passe Grafana

Alertes Recommandées

• Modification de variables sensibles
• Absence de fichiers .env
• Échec de chargement des variables
• Incohérence entre fichiers

Formation et Documentation

Équipe de Développement

• Formation sur la nouvelle structure
• Documentation des procédures
• Scripts de gestion et de test

Équipe DevOps

• Procédures de déploiement
• Gestion des variables sensibles
• Monitoring et alertes

Équipe de Sécurité

• Audit des variables sensibles
• Validation des procédures
• Contrôle d'accès aux fichiers

Conclusion

La nouvelle structure des variables d'environnement améliore la sécurité, la maintenabilité et la modularité du projet 4NK. Cette politique garantit une gestion cohérente et sécurisée des configurations tout en préservant la compatibilité avec l'existant.

Références

• Documentation de la nouvelle structure
• Scripts de gestion
• Configuration Docker Compose