4NK_vault/docs/templates-system.md

Système de Templates et Génération Automatisée

🎯 Vue d'ensemble

Le système de templates de 4NK Vault permet de générer automatiquement toutes les configurations nécessaires à partir de templates sources avec variables d'environnement. Cette approche garantit la cohérence, la maintenabilité et la sécurité des configurations.

🏗️ Architecture du Système

Workflow de Génération

templates/<env>/          →    Génération    →    storage/<env>/
├── .env.secrets          →    Scripts       →    ├── .env.auto
├── .env                  →    de génération →    ├── docker-compose.yml.auto
├── .env.post             →                  →    ├── _4NK_modules/
├── _4NK_modules/         →                  →    ├── 4NK_modules/
├── 4NK_modules/          →                  →    ├── logrotade/
└── nginx/                →                  →    └── nginx/

Séparation des Responsabilités

• templates/ : Fichiers sources avec variables ($VARIABLE)
• storage/ : Fichiers finaux avec variables résolues (lecture seule par API)
• Scripts de génération : Orchestrent la création et la résolution des variables

📋 Scripts de Génération

1. Script Principal : generate.sh

Orchestrateur principal qui exécute tous les scripts de génération dans l'ordre correct.

cd templates/dev
./generate.sh

Étapes d'exécution :

1. Génération des variables d'environnement
2. Génération des dashboards Grafana
3. Génération de la configuration Promtail
4. Génération des configurations logrotate
5. Génération des configurations nginx
6. Résolution des variables et copie vers storage/

2. Génération des Variables : generate_variables.sh

Génère les variables d'environnement et le fichier Docker Compose à partir des services définis.

Fonctionnalités :

• Génération des variables internes pour chaque service
• Génération des variables externes (URLs, ports)
• Création du fichier docker-compose.yml.auto
• Support des services externes (BOOTSTRAP, LECOFFRE_BACK_MINI)

Variables générées par service :

${SERVICE}_DOCKER_NAME=$SERVICE
${SERVICE}_CONFS_DIR=$DOCKER_GLOBAL/confs/$SERVICE
${SERVICE}_LOGS_DIR=$DOCKER_GLOBAL/logs/$SERVICE
${SERVICE}_DATAS_DIR=$DOCKER_GLOBAL/datas/$SERVICE
${SERVICE}_URL_ROUTE=/$SERVICE
${SERVICE}_URL=http://$SERVICE_DOCKER_NAME:$SERVICE_DOCKER_PORT
${SERVICE}_URL_EXTERNAL=https://$HOST$SERVICE_URL_ROUTE

3. Génération Grafana : generate_grafana_dashboards.sh

Génère automatiquement les dashboards Grafana pour tous les services.

Types de dashboards :

• Services Overview : Vue d'ensemble de tous les services
• Bitcoin Services : Dashboards spécialisés Bitcoin
• Frontend Services : Dashboards pour les interfaces utilisateur
• SDK Services : Dashboards pour les services SDK

4. Génération Promtail : generate_promtail_config.sh

Génère la configuration Promtail pour la collecte de logs.

Fonctionnalités :

• Configuration automatique des jobs de collecte
• Support des logs Docker et fichiers locaux
• Variables dynamiques pour les chemins de logs

5. Génération Logrotate : generate_logrotate_configs.sh

Génère les configurations logrotate pour tous les services.

Fonctionnalités :

• Rotation automatique des logs
• Compression et archivage
• Redémarrage des services après rotation

6. Génération Nginx : generate_nginx_configs.sh

Génère les configurations nginx pour tous les services.

Types de configurations :

• Upstreams pour les services
• Configurations HTTPS
• Headers proxy
• Ports internes

7. Résolution des Variables : replace_variables_and_copy.sh

Fonctionnalités principales :

• Chargement séquentiel des fichiers .env
• Résolution multi-passes des variables imbriquées
• Copie des fichiers traités vers storage/

Ordre de chargement :

1. .env.secrets - Variables sensibles
2. .env - Variables principales
3. .env.auto - Variables générées (avec résolution)
4. .env.post - Variables finales (avec résolution)

Résolution multi-passes :

• Jusqu'à 5 passes pour résoudre les variables imbriquées
• Protection contre les dépendances circulaires
• Export explicite de toutes les variables

🔧 Configuration des Variables

Structure des Fichiers d'Environnement

.env.secrets

Variables sensibles (clés API, mots de passe, etc.)

# Variables sensibles
API_SECRET_KEY=secret_value
DATABASE_PASSWORD=password

.env

Variables principales du système

# Configuration de base
ROOT_DIR=/home/debian/_4NK_env
DOMAIN=_4NKweb.com
HOST=dev4.$DOMAIN

# Services
export SERVICES=(
    "REDIS"
    "POSTGRESQL"
    "BITCOIN"
    # ...
)

# Services externes
export SERVICES_EXTERNAL=(
    "BOOTSTRAP"
    "LECOFFRE_BACK_MINI"
)

.env.post

Variables composites et finales

# URLs composites
SDK_RELAY_BOOSTRAP_URL=$BOOTSTRAP_URL_WS_EXTERNAL
RELAY_URLS=$SDK_RELAY_URL,$SDK_RELAY_BOOSTRAP_URL
BITCOIN_RPC_URL=http://$BITCOIN_DOCKER_NAME:$BITCOIN_SIGNET_RPC_PORT

Résolution des Variables

Exemple de Résolution Complexe

Variables de base :

ROOT_DIR=/home/debian/_4NK_env
DOCKER_GLOBAL_NAME=projects/lecoffre/lecoffre_node
BITCOIN=bitcoin

Variables intermédiaires :

DOCKER_GLOBAL=$ROOT_DIR/$DOCKER_GLOBAL_NAME

Variables finales :

BITCOIN_DATAS_DIR=$DOCKER_GLOBAL/datas/$BITCOIN

Résultat final :

BITCOIN_DATAS_DIR=/home/debian/_4NK_env/projects/lecoffre/lecoffre_node/datas/bitcoin

🚀 Utilisation

Génération Complète

# Générer toutes les configurations
cd templates/dev
./generate.sh

Génération Partielle

# Générer seulement les variables
./generate_variables.sh

# Générer seulement les dashboards Grafana
./generate_grafana_dashboards.sh

# Résoudre les variables et copier
./replace_variables_and_copy.sh

Vérification

# Vérifier les variables résolues
cd storage/dev
grep "datadir" _4NK_modules/bitcoin/bitcoin.conf
# Résultat: datadir=/home/debian/_4NK_env/projects/lecoffre/lecoffre_node/datas/bitcoin

# Vérifier les URLs externes
grep "BOOTSTRAP_URL_WS_EXTERNAL" .env.auto
# Résultat: BOOTSTRAP_URL_WS_EXTERNAL=wss://dev3._4NKweb.com:3006/ws

🔒 Sécurité

Protection des Templates

• Les fichiers dans templates/ ne sont jamais modifiés par l'API
• Seuls les fichiers dans storage/ sont accessibles via l'API
• Les fichiers .env.secrets ne sont jamais copiés dans storage/

Isolation des Environnements

• Chaque environnement (dev, prod) a ses propres templates
• Variables d'environnement isolées par environnement
• Pas de fuite de données entre environnements

🛠️ Maintenance

Ajout d'un Nouveau Service

1. Ajouter le service dans .env :

export SERVICES=(
    "REDIS"
    "POSTGRESQL"
    "NOUVEAU_SERVICE"  # Ajouter ici
    # ...
)

2. Définir les variables du service :

NOUVEAU_SERVICE=nouveau_service
NOUVEAU_SERVICE_IMAGE=image:tag
NOUVEAU_SERVICE_PORT=8080:8080

3. Régénérer les configurations :

cd templates/dev
./generate.sh

Modification des Variables

1. Modifier les fichiers appropriés dans templates/dev/
2. Régénérer les configurations :

cd templates/dev
./generate.sh

3. Vérifier les résultats dans storage/dev/

📊 Monitoring

Logs de Génération

Les scripts de génération fournissent des logs détaillés :

• Nombre de variables chargées
• Fichiers traités et copiés
• Erreurs de résolution des variables

Validation

• Vérification automatique des variables non résolues
• Protection contre les dépendances circulaires
• Validation des chemins et permissions

🔄 Intégration avec l'API

L'API 4NK Vault lit uniquement les fichiers dans storage/<env>/ et ne traite plus les variables d'environnement. Cette séparation garantit :

• Performance : Pas de traitement de variables en temps réel
• Fiabilité : Variables pré-résolues et validées
• Sécurité : Isolation entre templates et fichiers finaux
• Maintenabilité : Workflow de génération automatisé et reproductible