From aad486cf54763b77fa94ee6401ae69b81d90a414 Mon Sep 17 00:00:00 2001 From: root Date: Mon, 8 Sep 2025 22:12:18 +0200 Subject: [PATCH] Configuration hybride: Docker + services locaux MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Suppression services IA/monitoring du docker-compose.yml (externalisés vers 4NK_IA) - Configuration Nginx local proxy vers ports Docker exposés - Installation et configuration Grafana local pour monitoring - Suppression doublon miniback (remplacé par coffre_back_mini) - Documentation mise à jour pour architecture hybride - Configuration monitoring compatible avec logs Docker --- CHANGELOG.md | 11 +++ docker-compose.yml | 138 ------------------------------------ docs/ARCHITECTURE.md | 66 ++++++++++++++--- docs/CONFIGURATION.md | 64 ++++++++++------- docs/USAGE.md | 61 +++++++++++----- log/grafana-dashboards.yml | 11 ++- log/grafana-datasources.yml | 11 ++- 7 files changed, 165 insertions(+), 197 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 67e377e5..80e0e660 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,17 @@ ### Added - Mise à jour mineure de versionnage et documentation (ALIGNEMENT VERSION / TESTS) +### Documentation +- ARCHITECTURE.md : ajout des sections Contexte, Composants, Réseaux, Flux, Données, Sécurité, Observabilité, Décisions. +- CONFIGURATION.md : consolidation des tags `:dev`, réseaux, montages, variables, healthchecks, routage et procédures usuelles sans modifier les fichiers de configuration. +- USAGE.md : mise à jour pour la configuration hybride (Docker + services locaux Nginx/Grafana). + +### Configuration +- docker-compose.yml : suppression des services `nginx`, `grafana`, `ollama`, `anythingllm`, `loki`, `promtail`, `devtools`, `miniback` (services externalisés, locaux ou doublons). +- Installation locale : Nginx et Grafana installés et configurés localement selon la documentation. +- Services IA : Externalisés vers le repository [4NK_IA](https://git.4nkweb.com/4nk/4NK_IA.git) sur le tag `dev`. +- Configuration hybride : Nginx local proxy vers les ports Docker exposés (127.0.0.1), Grafana local configuré pour le monitoring. + ## [1.1.2] - 2025-08-27 ### Added diff --git a/docker-compose.yml b/docker-compose.yml index faaf115e..535e5b88 100644 --- a/docker-compose.yml +++ b/docker-compose.yml @@ -241,21 +241,6 @@ services: ports: - "5432:5432" - miniback: - image: 4nk-node-miniback:dev - container_name: miniback - hostname: miniback.4nk.local - env_file: - - ./projects/lecoffre/lecoffre-back-mini/conf/lecoffre-back-mini_env.conf - depends_on: - - miniback-postgres - networks: - 4nk_network: - ipv4_address: 172.20.0.31 - restart: unless-stopped - volumes: - - ./projects/lecoffre/lecoffre-back-mini/logs:/logs - - ./projects/lecoffre/lecoffre-back-mini/conf/lecoffre-back-mini_env.conf:/app/.env:ro coffre_front: image: lecoffre-front:dev @@ -277,133 +262,10 @@ services: ipv4_address: 172.20.0.33 restart: unless-stopped - nginx: - image: nginx:1.25 - container_name: 4nk-nginx - hostname: nginx.4nk.local - ports: - - "80:80" - volumes: - - ./conf/nginx/nginx.conf:/etc/nginx/nginx.conf:ro - - ./conf/nginx/sites-enabled:/etc/nginx/sites-enabled:ro - - ./log/nginx:/var/log/nginx - networks: - 4nk_network: - ipv4_address: 172.20.0.40 - restart: unless-stopped - # IA locale: Ollama + AnythingLLM - ollama: - image: ollama/ollama:latest - container_name: 4nk-ollama - hostname: ollama.4nk.local - ports: - - "11434:11434" - environment: - - OLLAMA_HOST=0.0.0.0 - volumes: - - ./modules/local_IA/data:/root/.ollama - - ./modules/local_IA/logs:/var/log/ollama - networks: - 4nk_network: - ipv4_address: 172.20.0.50 - restart: unless-stopped - anythingllm: - image: mintplexlabs/anythingllm:latest - container_name: 4nk-anythingllm - hostname: anythingllm.4nk.local - ports: - - "3001:3001" - environment: - - SERVER_PORT=3001 - - OLLAMA_URL=http://ollama.4nk.local:11434 - volumes: - - ./modules/local_IA/conf:/app/config - - ./modules/local_IA/data:/app/storage - - ./modules/local_IA/logs:/app/logs - networks: - 4nk_network: - ipv4_address: 172.20.0.51 - depends_on: - - ollama - restart: unless-stopped - # Profil monitoring: Loki + Promtail + Grafana - loki: - image: grafana/loki:2.9.0 - container_name: 4nk-loki - ports: - - "3100:3100" - command: -config.file=/etc/loki/local-config.yaml - volumes: - - ./log/loki-config.yaml:/etc/loki/local-config.yaml:ro - - loki_data:/loki - networks: - 4nk_network: - ipv4_address: 172.20.0.41 - restart: unless-stopped - promtail: - image: grafana/promtail:2.9.0 - container_name: 4nk-promtail - command: -config.file=/etc/promtail/config.yml - volumes: - - ./log/promtail-config.yml:/etc/promtail/config.yml:ro - - /var/lib/docker/containers:/var/lib/docker/containers:ro - - /var/log/docker:/var/log/docker:ro - - ./modules:/workspace/modules:ro - - ./projects:/workspace/projects:ro - - ./log:/workspace/logs:ro - networks: - 4nk_network: - ipv4_address: 172.20.0.42 - restart: unless-stopped - depends_on: - - loki - - grafana: - image: grafana/grafana:10.0.0 - container_name: 4nk-grafana - ports: - - "3000:3000" - environment: - - GF_SECURITY_ADMIN_PASSWORD=admin - - GF_USERS_ALLOW_SIGN_UP=false - - GF_SERVER_ROOT_URL=%(protocol)s://%(domain)s/grafana - - GF_SERVER_SERVE_FROM_SUB_PATH=true - volumes: - - grafana_data:/var/lib/grafana - - ./log/grafana-datasources.yml:/etc/grafana/provisioning/datasources/datasources.yml:ro - - ./log/grafana-dashboards.yml:/etc/grafana/provisioning/dashboards/dashboards.yml:ro - - ./log/dashboards:/etc/grafana/provisioning/dashboards/dashboards:ro - networks: - 4nk_network: - ipv4_address: 172.20.0.43 - restart: unless-stopped - depends_on: - - loki - - # Profil outils de développement et diagnostic - devtools: - image: alpine:3.19 - container_name: 4nk-devtools - command: ["sh", "-c", "sleep infinity"] - tty: true - stdin_open: true - volumes: - - ./log:/workspace/logs - - ./modules:/workspace/modules:ro - - ./projects:/workspace/projects:ro - networks: - 4nk_network: - ipv4_address: 172.20.0.44 - restart: unless-stopped - healthcheck: - test: ["CMD", "sh", "-lc", "apk info >/dev/null 2>&1"] - interval: 30s - timeout: 5s - retries: 3 volumes: diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index b6cddea0..e309410b 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -1,20 +1,68 @@ -## ARCHITECTURE +## Architecture -## Contexte +### Contexte -## Composants +Cette page décrit l’architecture fonctionnelle et technique de `4NK_node`, un orchestrateur local des services 4NK s’appuyant principalement sur Docker, avec la possibilité d’exécuter certains outils (Nginx, Grafana) localement selon `docs/USAGE.md`. L’objectif est de fournir une stack reproductible pour le développement, la démonstration et les tests des composants 4NK (réseau de relais, stockage, signer, intégrations Bitcoin/Blindbit) en environnement isolé. -## Flux et dépendances +### Composants -## Données et modèles +- Tor : proxy d’anonymisation utilisé par Bitcoin Core. +- Bitcoin Core (signet) : nœud de référence pour RPC et notifications ZMQ. +- Blindbit : service d’indexation et filtres pour Silent Payments. +- SDK Storage : service d’API interne consommé par les relais. +- SDK Relay (1/2/3) : frontaux temps réel (HTTP/WS) consommant Storage. +- SDK Signer : service d’orchestration cryptographique connecté aux relais. +- IHM client : interface utilisateur consommant le Signer. +- Services IA : Externalisés vers le repository [4NK_IA](https://git.4nkweb.com/4nk/4NK_IA.git) (tag `dev`). +- Observabilité : Grafana (exécuté localement hors Docker conformément à USAGE). +- Reverse‑proxy : Nginx (peut être exécuté localement hors Docker conformément à USAGE). -## Sécurité +### Réseaux et adresses -## Observabilité +- Réseau principal : `4nk_network` en 172.20.0.0/16, IP statiques et hostnames Docker en `.4nk.local`. +- Réseau projets : `4nk_projects_net` en 172.21.0.0/16 (réservé, non attaché par défaut). + +### Flux et dépendances + +1. Tor → Bitcoin Core : Bitcoin utilise Tor comme proxy (SOCKS) et active l’écoute onion si supportée. +2. Bitcoin Core → Blindbit : Blindbit consomme RPC/ZMQ pour construire ses index. +3. Blindbit → SDK Storage : Storage s’appuie sur les données/indices fournis par Blindbit. +4. SDK Storage → SDK Relays (1/2/3) : les relais interrogent l’API HTTP de Storage et exposent des WebSockets dédiés. +5. SDK Relays → SDK Signer : Signer dépend des trois relais (WS/HTTP) et de Storage. +6. SDK Signer → IHM : l’IHM consomme Signer (WS/HTTP) via le reverse‑proxy. +7. Nginx → Services HTTP/WS : expose des routes stables (`/relayX/`, `/signer/`, `/sdk_storage/`, `/blindbit/`, `/grafana/`, etc.). + +### Données et modèles + +- Données Bitcoin : blockchain signet, cookie RPC, logs. +- Données Blindbit/Storage : index, caches, journaux applicatifs. +- Données Relays/Signer : artefacts temporaires, métriques et logs d’exécution. +- Données IHM et projets : fichiers d’application, artefacts runtime, logs. +- Les répertoires de données et journaux sont montés depuis `modules/*/{data,logs}` et `projects/*/*/{data,logs}` afin d’assurer la persistance locale et la collecte d’observabilité. + +### Sécurité + +- Cloisonnement par réseau Docker dédié (`4nk_network`) avec IP et hostnames statiques. +- Élévation minimale des privilèges côté services (redémarrage automatique, volumes en lecture seule pour les fichiers de configuration quand possible). +- Secrets et accès : utilisation d’authentifiants côté RPC Bitcoin et isolation des volumes. +- Reverse‑proxy : terminaisons HTTP/WS centralisées, possibilité d’un durcissement local de Nginx (CSP, CORS, headers sécurité) lorsqu’il est exécuté en dehors de Docker. +- Alerte : aucune CI active pour l’instant (cf. décision produit), donc l’audit de sécurité automatisé n’est pas encore orchestré. + +### Observabilité + +- Grafana installé localement pour la visualisation des métriques et logs. +- Des healthchecks applicatifs sont définis sur les services HTTP/WS pour une supervision de base. +- Les services IA et leur monitoring sont externalisés vers le repository [4NK_IA](https://git.4nkweb.com/4nk/4NK_IA.git). ### Politique des images - Externes : Tor (`torproject/tor:latest`), Bitcoin Core (`ruimarinho/bitcoin-core:latest`), Blindbit (`4nk-node-blindbit:latest`). -- Internes : images taguées `:dev` en cours de création (sdk_storage, sdk_relay1/2/3, sdk_signer, ihm_client, miniback, lecoffre-front, lecoffre-back-mini). +- Internes : images taguées `:dev` (référence principale dans ce dépôt) pour `sdk_storage`, `sdk_relay1/2/3`, `sdk_signer`, `ihm_client`, `miniback`, `lecoffre-front`, `lecoffre-back-mini`. -Les hostnames internes sont fixés en `.4nk.local` et une IP statique est réservée par service sur `4nk_network`. +Cette politique s’aligne avec la stratégie locale : les tags `:dev` sont utilisés tant que les pipelines de publication ne requièrent pas de tag spécifique. + +### Décisions et implications + +- Exécution locale possible de Nginx et Grafana conformément à `USAGE.md` : ne pas modifier les fichiers de configuration, mais documenter les points d’intégration et de provisioning. +- Réservation d’IP statiques et de hostnames `.4nk.local` : simplifie le routage et la documentation réseau. +- Pas de workflow CI pour l’instant : les validations (tests/documentation) sont manuelles et locales. diff --git a/docs/CONFIGURATION.md b/docs/CONFIGURATION.md index 1e91f4b7..ba73200c 100644 --- a/docs/CONFIGURATION.md +++ b/docs/CONFIGURATION.md @@ -1,34 +1,50 @@ -## Configuration des images et tags +## Configuration des images, réseaux et paramètres -### Introduction +### Politique de tags -Ce document précise l'état courant de la politique de tags d'images et leur utilisation dans l'orchestrateur de `4NK_node`. - -### Politique de tags (en cours de création) - -- Les tags de build « dev » sont en cours de création pour les services applicatifs internes. -- À date, l'orchestrateur référence : - - Images externes stables (inchangées) : `torproject/tor:latest`, `ruimarinho/bitcoin-core:latest` et `4nk-node-blindbit:latest`. - - Images internes basculées sur le tag « dev » (en attente de disponibilité sur le registre) : - - `4nk-node-sdk_storage:dev` - - `4nk-node-sdk_relay1:dev`, `4nk-node-sdk_relay2:dev`, `4nk-node-sdk_relay3:dev` - - `4nk-node-sdk_signer:dev` - - `4nk-node-ihm_client:dev` - - `4nk-node-miniback:dev` - - `lecoffre-front:dev`, `lecoffre-back-mini:dev` - -Lorsque les tags « dev » seront effectivement publiés, un `docker compose pull` puis un redémarrage permettront d'aligner les environnements. +- Référence locale : tags internes `:dev` (services 4NK) utilisés par défaut dans `docker-compose.yml`. +- Images externes stables : `torproject/tor:latest`, `ruimarinho/bitcoin-core:latest`, `4nk-node-blindbit:latest`. +- Alignement documentaire : la stratégie `:dev` est retenue pour cet environnement. Aucune modification de fichiers de configuration n’est effectuée par ce document. ### Réseaux et adresses -- Réseau principal `4nk_network` : `172.20.0.0/16`, IP et hostnames statiques par service. -- Réseau réservé projets `4nk_projects_net` : `172.21.0.0/16` (aucun service attaché pour l'instant). +- `4nk_network` : `172.20.0.0/16` avec IP statiques et hostnames `.4nk.local` par service. +- `4nk_projects_net` : `172.21.0.0/16` réservé pour des projets additionnels. -### Montages de configuration et journaux +### Montages (configuration, données, logs) -- Les fichiers de configuration sont montés depuis `modules/*/conf` et `projects/*/*/conf`. -- Les journaux applicatifs sont montés depuis `modules/*/logs` et `projects/*/*/logs` pour observabilité. +- Configuration : montée en lecture seule lorsque possible depuis `modules/*/conf` et `projects/*/*/conf`. +- Données : volumes persistants locaux (`modules/*/data`, `projects/*/*/data`). +- Journaux : `modules/*/logs`, `projects/*/*/logs`, et `./log` pour la stack d’observabilité. + +### Variables d’environnement (exemples typés) + +- Journalisation : + - `RUST_LOG` : chaîne (ex. `debug,bitcoincore_rpc=trace`). +- Bitcoin : + - `BITCOIN_COOKIE_PATH` : chemin absolu vers le cookie RPC. +- Synchronisation (selon besoins locaux) : + - `ENABLE_SYNC_TEST` : booléen (0/1) activant certains scénarios de test. + +Nota : ces variables sont documentées pour référence et ne modifient pas la configuration existante. + +### Healthchecks et supervision + +- Services HTTP/WS instrumentés par des healthchecks (requêtes HTTP simples sur ports exposés). +- Stack observabilité : Promtail collecte les logs montés et les pousse vers Loki ; Grafana consomme Loki. +- Conformément à `USAGE.md`, Grafana peut être exécuté localement (hors Docker) ou via le service de l’orchestrateur. + +### Nginx et routage + +- Nginx agit en reverse‑proxy et expose des routes stables : `/`, `/blindbit/`, `/sdk_storage/`, `/relay1|2|3/` (+ `/ws/`), `/signer/` (+ `/ws/`), `/coffre/`, `/grafana/`. +- L’exécution locale (hors Docker) est supportée ; les fichiers de configuration existants ne sont pas modifiés par ce document. + +### Procédures usuelles (sans modification de conf) + +- Vérifier les images : `docker compose pull`. +- Démarrer la stack : `docker compose up -d` (ou exécutions locales pour Nginx/Grafana, selon `USAGE.md`). +- Consulter les logs : via `docker compose logs` ou les fichiers montés. ### Conclusion -Les tags « dev » sont en cours de création et déjà référencés dans l'orchestrateur afin d'anticiper leur disponibilité. Cette page sera actualisée dès publication effective. Les mises à jour corrélées sont reflétées dans `docs/ARCHITECTURE.md` et le `CHANGELOG.md`. +Cette page consolide les paramètres clefs (tags `:dev`, topologie réseau, montages, variables, healthchecks, routage) afin d’harmoniser l’usage sans modifier les fichiers de configuration. Les évolutions futures seront répercutées dans `docs/ARCHITECTURE.md` et consignées dans `CHANGELOG.md`. diff --git a/docs/USAGE.md b/docs/USAGE.md index 80792e8c..92e9b62e 100644 --- a/docs/USAGE.md +++ b/docs/USAGE.md @@ -3,7 +3,8 @@ ## Prérequis - Docker et docker compose installés -- Nginx utilisé via le service `nginx` de l'orchestrateur +- Nginx installé localement (hors Docker) +- Grafana installé localement (hors Docker) ## Installation locale @@ -13,35 +14,61 @@ ## Démarrage -- Démarrer la stack applicative : `docker compose up -d` -- Démarrer la stack de monitoring (Loki/Promtail/Grafana) si souhaité : `docker compose -f log-monitoring.yml up -d` -- Accéder aux services via Nginx : - - IHM: `http://localhost/` - - Blindbit: `http://localhost/blindbit/` - - SDK Storage: `http://localhost/sdk_storage/` - - Relais HTTP: `http://localhost/relay1/`, `/relay2/`, `/relay3/` - - Relais WebSocket: `ws://localhost/relay1/ws/` (idem `relay2`, `relay3`) - - Signer WS: `ws://localhost/signer/ws/`; HTTP: `http://localhost/signer/` - - Coffre front: `http://localhost/coffre/` - - Grafana: `http://localhost/grafana/` +### Services Docker +- Démarrer la stack applicative : `docker compose up -d` + +### Services locaux +- Démarrer Nginx local : `systemctl start nginx` +- Démarrer Grafana local : `systemctl start grafana-server` + +### Services IA (optionnel) +- Cloner le repository IA : `git clone https://git.4nkweb.com/4nk/4NK_IA.git` +- Basculer sur le tag dev : `cd 4NK_IA && git checkout dev` +- Suivre les instructions d'installation dans le repository 4NK_IA + +### Accès aux services +- IHM: `http://localhost/` +- Blindbit: `http://localhost/blindbit/` +- SDK Storage: `http://localhost/sdk_storage/` +- Relais HTTP: `http://localhost/relay1/`, `/relay2/`, `/relay3/` +- Relais WebSocket: `ws://localhost/relay1/ws/` (idem `relay2`, `relay3`) +- Signer WS: `ws://localhost/signer/ws/`; HTTP: `http://localhost/signer/` +- Coffre: `http://localhost/coffre/` +- Grafana: `http://localhost:3000/` (direct) ou `http://localhost/grafana/` (via Nginx) ## Commandes utiles +### Docker - Mettre à jour les images: `docker compose pull` -- Voir les logs Nginx: `tail -f log/nginx/4nk_node.access.log` - Voir les logs des services (montés): `tail -f modules//logs/*` -- Logs Promtail/Loki/Grafana: voir `log/` et `log-monitoring.yml` + +### Services locaux +- Voir les logs Nginx: `tail -f /var/log/nginx/4nk_node.access.log` +- Voir les logs Grafana: `journalctl -u grafana-server -f` +- Redémarrer Nginx: `systemctl restart nginx` +- Redémarrer Grafana: `systemctl restart grafana-server` + +### Monitoring +- Grafana local: `http://localhost:3000/` (admin/admin) +- Logs des services Docker: montés dans `modules/*/logs/` et `projects/*/*/logs/` +- Configuration Grafana: `log/grafana-datasources.yml` et `log/grafana-dashboards.yml` ## Dépannage +### Docker - Vérifier les hostnames Docker internes (DNS du réseau `4nk_network`): voir `docker-compose.yml` -- Les tags `:dev` sont en cours de création; en cas d’indisponibilité, utiliser des tags stables temporaires +- Les tags `:dev` sont en cours de création; en cas d'indisponibilité, utiliser des tags stables temporaires - Conf Tor: `modules/tor/conf/tor.conf` est montée si l'image Tor supporte `/etc/tor/torrc` -- Le reverse proxy Nginx s’appuie sur les hostnames Docker (`*.4nk.local`); en cas de changement d’IP/hostnames, mettre à jour `docker-compose.yml` et relancer `nginx`. + +### Services locaux +- Nginx: vérifier la configuration avec `nginx -t` +- Grafana: vérifier le statut avec `systemctl status grafana-server` +- Le reverse proxy Nginx pointe vers `127.0.0.1` avec les ports exposés par Docker Compose +- En cas de changement de ports dans `docker-compose.yml`, mettre à jour `conf/nginx/sites-enabled/4nk_node.conf` ## Accès depuis Windows (WSL2 ou VM Linux) - WSL2 (Docker dans WSL): accéder via le navigateur Windows à `http://localhost/`. Si non accessible, utiliser l’IP WSL (`wsl hostname -I` côté PowerShell) et ouvrir `http:///`. - VM Linux (Hyper‑V/VirtualBox/VMware): utiliser l’IP de la VM (`ip addr` dans la VM) et ouvrir `http:///`. - Les routes exposées par Nginx: `/`, `/blindbit/`, `/sdk_storage/`, `/relay1/`, `/relay2/`, `/relay3/`, `/signer/`, `/coffre/`, `/grafana/`. - - IA locale: `/ollama/` (API Ollama), `/anythingllm/` (AnythingLLM) \ No newline at end of file + - Services IA: voir le repository [4NK_IA](https://git.4nkweb.com/4nk/4NK_IA.git) sur le tag `dev` \ No newline at end of file diff --git a/log/grafana-dashboards.yml b/log/grafana-dashboards.yml index c5375226..89f7165a 100644 --- a/log/grafana-dashboards.yml +++ b/log/grafana-dashboards.yml @@ -1,13 +1,12 @@ apiVersion: 1 providers: - - name: '4NK Dashboards' + - name: '4NK Node Dashboards' orgId: 1 - folder: '4NK' + folder: '4NK Node' type: file disableDeletion: false - editable: true - updateIntervalSeconds: 30 + updateIntervalSeconds: 10 + allowUiUpdates: true options: - path: /etc/grafana/provisioning/dashboards/dashboards -EOF + path: /etc/grafana/provisioning/dashboards/dashboards \ No newline at end of file diff --git a/log/grafana-datasources.yml b/log/grafana-datasources.yml index 21652f8e..452fac63 100644 --- a/log/grafana-datasources.yml +++ b/log/grafana-datasources.yml @@ -4,8 +4,13 @@ datasources: - name: Loki type: loki access: proxy - url: http://loki:3100 + url: http://localhost:3100 isDefault: true + editable: true jsonData: - maxLines: 5000 -EOF + maxLines: 1000 + derivedFields: + - datasourceUid: loki + matcherRegex: "container_name=(\\w+)" + name: "Container" + url: "/d/${__value.raw}" \ No newline at end of file