From 8ba17169be198492885c46afeae947f9b15c73ba Mon Sep 17 00:00:00 2001 From: Nicolas Cantu Date: Wed, 10 Sep 2025 12:29:45 +0200 Subject: [PATCH] =?UTF-8?q?docs:=20documentation=20compl=C3=A8te=20(archit?= =?UTF-8?q?ecture,=20CI,=20submodules,=20docker,=20release,=20dev,=20scrip?= =?UTF-8?q?ts,=20FAQ)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/architecture.md | 13 ++++ docs/ci.md | 21 ++++++ docs/ci_dev_test.md | 35 ---------- docs/development.md | 13 ++++ docs/docker_registry.md | 6 ++ docs/etat_services.md | 127 ------------------------------------- docs/faq.md | 15 +++++ docs/index.md | 24 +++++++ docs/release_versioning.md | 7 ++ docs/scripts.md | 16 +++++ docs/submodules.md | 11 ++++ 11 files changed, 126 insertions(+), 162 deletions(-) create mode 100644 docs/architecture.md create mode 100644 docs/ci.md delete mode 100644 docs/ci_dev_test.md create mode 100644 docs/development.md create mode 100644 docs/docker_registry.md delete mode 100644 docs/etat_services.md create mode 100644 docs/faq.md create mode 100644 docs/index.md create mode 100644 docs/release_versioning.md create mode 100644 docs/scripts.md create mode 100644 docs/submodules.md diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..216ecdd --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,13 @@ +# Architecture + +## Arborescence + +- `modules/`: dépôts modulaires (SDK, clients, outils) +- `deploy/`: dépôts de déploiement (ex: `deploy/4NK_node`) +- `projects//`: dépôts par projets (ex: `projects/lecoffre/...`) + +## Principes + +- Submodules décrits dans `.gitmodules` avec `path`, `url`, `branch`. +- CI centrale dans `/.gitea/workflows/` pour build/push Docker. +- Images taggées par `DOCKER_TAG`. diff --git a/docs/ci.md b/docs/ci.md new file mode 100644 index 0000000..4d5edb7 --- /dev/null +++ b/docs/ci.md @@ -0,0 +1,21 @@ +# Intégration Continue (CI) + +## Workflow + +- Fichier: `.gitea/workflows/dev.yml` +- Triggers: + - Push sur `dev` + - Push sur branches `dev-test*` modifiant `.ci/tag.env` + - Tag `dev` + +## Résolution de DOCKER_TAG + +1. Motif dans le dernier message de commit: `ci: docker_tag=` +2. Fichier `.ci/tag.env` (clé `DOCKER_TAG=`) +3. Nom de la branche (`GITHUB_REF_NAME`) +4. Secours: `dev-test` + +## Build + +- Script: `scripts/build_and_push.sh ` (obligatoire) +- Parcourt les submodules; build/push si `Dockerfile` présent. diff --git a/docs/ci_dev_test.md b/docs/ci_dev_test.md deleted file mode 100644 index 503f4ef..0000000 --- a/docs/ci_dev_test.md +++ /dev/null @@ -1,35 +0,0 @@ -# Politique CI "dev-test" - -Ce flux construit et pousse des images Docker pour chaque sous-dépôt listé dans `.gitmodules` qui contient un `Dockerfile`. Les images sont poussées dans le registry Gitea `git.4nkweb.com` sous le namespace `4nk` avec le tag `dev-test`. - -## Déclencheur - -- Tag Git: `dev-test` - -## Séquence - -1. Checkout du dépôt avec submodules (recursive) -2. Synchronisation des submodules sur la branche déclarée dans `.gitmodules` -3. Authentification au registry Gitea via secrets `REGISTRY_USERNAME` et `REGISTRY_PASSWORD` -4. Build et push des images Docker présentes dans chaque sous-module - -## Variables d’environnement - -- `REGISTRY`: `git.4nkweb.com` -- `NAMESPACE`: `4nk` -- `DOCKER_TAG`: `dev-test` - -## Scripts - -- `scripts/sync_submodules.sh`: synchronise les branches des submodules -- `scripts/build_and_push.sh`: build et push les images existantes - -## Secrets requis - -- `REGISTRY_USERNAME`: compte autorisé sur le registry -- `REGISTRY_PASSWORD`: mot de passe ou token - -## Notes - -- Les submodules sans `Dockerfile` sont ignorés. -- Les branches utilisées sont celles définies dans `.gitmodules` (clé `branch`). diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..22202a7 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,13 @@ +# Développement local + +## Prérequis + +- Git + accès SSH à `git.4nkweb.com` +- Docker + Buildx + +## Commandes utiles + +- Synchroniser submodules: `git submodule sync --recursive` +- Initialiser/mettre à jour: `git submodule update --init --recursive` +- Déclencher CI via branche: `scripts/commit_tag_env.sh ` +- Taguer tous les repos: `scripts/tag.sh ` diff --git a/docs/docker_registry.md b/docs/docker_registry.md new file mode 100644 index 0000000..cffa376 --- /dev/null +++ b/docs/docker_registry.md @@ -0,0 +1,6 @@ +# Registry Docker + +- Registry: `git.4nkweb.com` +- Namespace: `4nk` +- Tagging: basé sur `DOCKER_TAG` (obligatoire) +- Politique: ne jamais utiliser ni modifier un tag Docker `dev`. diff --git a/docs/etat_services.md b/docs/etat_services.md deleted file mode 100644 index 05715e1..0000000 --- a/docs/etat_services.md +++ /dev/null @@ -1,127 +0,0 @@ -# État des Services 4NK Node - -**Date :** 3 septembre 2025 -**Heure :** 18:10 UTC -**Environnement :** Docker Compose sur Debian - -## Résumé Global - -- **Services fonctionnels :** 4/7 (57%) ⬆️ -- **Services en erreur :** 3/7 (43%) ⬇️ -- **Services redémarrant :** 0/7 (0%) ✅ - -## Détail des Services - -### ✅ Services Fonctionnels - -#### 1. **4nk-bitcoin** (bitcoin) -- **Statut :** `Up About a minute` -- **Ports :** 29000, 18443, 38332-38333 -- **État :** ✅ **FONCTIONNEL - RPC corrigé** -- **Notes :** Credentials RPC ajoutés, réseau Docker autorisé (192.168.240.0/20) - -#### 2. **4nk-tor** (tor) -- **Statut :** `Up 2 hours` -- **Ports :** 9050-9051 -- **État :** ✅ **FONCTIONNEL** -- **Notes :** Service Tor opérationnel, listeners SOCKS et Control actifs - -#### 3. **4nk-blindbit** (blindbit) ⭐ **CORRIGÉ** -- **Statut :** `Up 31 seconds (health: starting)` -- **Ports :** 8000 -- **État :** ✅ **FONCTIONNEL - RPC authentifié** -- **Notes :** Connexion RPC réussie, synchronisation active, service HTTP opérationnel - -#### 4. **4nk-sdk-storage** (sdk_storage) -- **Statut :** `Up 2 hours (unhealthy)` -- **Ports :** 8081 -- **État :** ✅ **FONCTIONNEL mais non vérifié** -- **Notes :** Service démarré mais health check échoue - -### ❌ Services en Erreur - -#### 5. **4nk-sdk-signer** (sdk_signer) -- **Statut :** `Arrêté` -- **Erreur :** `SyntaxError: Unexpected token 'export'` -- **Cause :** Incompatibilité ES modules vs CommonJS -- **Fichier problématique :** `/app/pkg/sdk_client.js` -- **Détail :** Le code WASM généré utilise la syntaxe ES6 `export` mais Node.js s'attend à du CommonJS - -#### 6. **4nk-sdk-relay** (sdk_relay) -- **Statut :** `Arrêté` -- **Erreur :** `Failed to find conf file` -- **Cause :** Fichier de configuration manquant -- **Impact :** Service critique pour la communication entre composants - -#### 7. **4nk-ihm-client** (ihm_client) -- **Statut :** `Up 2 hours (unhealthy)` -- **Ports :** 3003, 8080 -- **État :** ✅ **Démarré mais non vérifié** -- **Notes :** Interface utilisateur accessible mais health check échoue - -## Problèmes Résolus ✅ - -### **Authentification RPC Bitcoin-BlindBit (RÉSOLU)** -- **Problème :** BlindBit recevait des erreurs 403 Forbidden -- **Cause :** Configuration réseau incorrecte (`rpcallowip=172.24.0.0/16` au lieu de `192.168.240.0/20`) -- **Solution :** - 1. Ajout des credentials RPC (`rpcuser=bitcoin`, `rpcpassword=bitcoin`) - 2. Correction du réseau autorisé (`rpcallowip=192.168.240.0/20`) - 3. Redémarrage de Bitcoin pour appliquer la configuration -- **Résultat :** BlindBit se connecte maintenant avec succès à Bitcoin - -## Problèmes Identifiés - -### 1. **Incompatibilité ES Modules (CRITIQUE)** -- **Service :** sdk_signer -- **Problème :** Le code WASM généré par `wasm-pack` utilise la syntaxe ES6 -- **Solution :** Configurer le projet pour utiliser ES modules ou convertir en CommonJS - -### 2. **Configuration Manquante (CRITIQUE)** -- **Service :** sdk_relay -- **Problème :** Fichier de configuration introuvable -- **Solution :** Vérifier la présence et la validité des fichiers de config - -### 3. **Health Checks (FAIBLE)** -- **Services :** sdk_storage, ihm_client -- **Problème :** Health checks échouent malgré un fonctionnement apparent -- **Solution :** Ajuster les critères de health check - -## Recommandations - -### Priorité 1 : Corriger sdk_signer ✅ -- **Statut :** En attente -- **Action :** Résoudre l'incompatibilité ES modules - -### Priorité 2 : Corriger sdk_relay ✅ -- **Statut :** En attente -- **Action :** Identifier et corriger le fichier de configuration manquant - -### Priorité 3 : Améliorer les health checks ✅ -- **Statut :** En attente -- **Action :** Ajuster les critères de vérification - -## Actions Effectuées - -1. ✅ **Ajouté les credentials RPC** dans `conf/bitcoin.conf` -2. ✅ **Corrigé la configuration réseau** (`rpcallowip=192.168.240.0/20`) -3. ✅ **Redémarré Bitcoin** pour appliquer la configuration -4. ✅ **Testé la connexion RPC** avec succès -5. ✅ **Relancé BlindBit** avec succès -6. ✅ **Vérifié le fonctionnement** du service - -## Impact sur l'Architecture - -- **Communication inter-services :** ✅ BlindBit-Bitcoin fonctionne -- **Signature des transactions :** ❌ Impossible (sdk_signer défaillant) -- **Confidentialité :** ✅ **Disponible (blindbit fonctionnel)** -- **Interface utilisateur :** Partiellement fonctionnelle -- **Stockage :** Fonctionnel mais non vérifié - -## Prochaines Étapes - -1. ✅ **BlindBit corrigé** - Service opérationnel -2. 🔄 **Corriger sdk_signer** - Résoudre l'incompatibilité ES modules -3. 🔄 **Corriger sdk_relay** - Résoudre la configuration manquante -4. 🔄 **Améliorer les health checks** - Optimiser la surveillance des services -5. 🔄 **Tester l'intégration complète** - Vérifier la communication inter-services diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 0000000..01658b4 --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,15 @@ +# FAQ + +## Est-ce que la CI s’applique aux submodules ? + +- Oui pour le build/push Docker (via 4NK_dev), non pour déclencher leur CI interne. + +## Comment choisir le tag d’image ? + +- Message de commit: `ci: docker_tag=` +- Ou `.ci/tag.env` via branche dédiée +- Ou nom de la branche + +## Le tag Docker `dev` est-il utilisé ? + +- Non. Il ne doit jamais être utilisé ni modifié. diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..e08e90f --- /dev/null +++ b/docs/index.md @@ -0,0 +1,24 @@ +# 4NK_dev — Documentation du projet + +## Objectif du dépôt + +- Dépôt agrégateur des projets 4NK via submodules Git. +- Normalise l’arborescence: `modules/`, `deploy/`, `projects//`. +- Centralise CI de build/push d’images Docker pour chaque submodule éligible. + +## Contenu de la documentation + +- Architecture: voir `architecture.md` +- Submodules: voir `submodules.md` +- CI et publication Docker: voir `ci.md` +- Registry et tags: voir `docker_registry.md` +- Versioning et release: voir `release_versioning.md` +- Développement local: voir `development.md` +- Scripts utilitaires: voir `scripts.md` +- FAQ: voir `faq.md` + +## Conventions + +- Lint Markdown appliqué. +- Pas d’exemples dans la documentation. +- Les changements doivent toujours être décrits dans `CHANGELOG.md` et `VERSION`. diff --git a/docs/release_versioning.md b/docs/release_versioning.md new file mode 100644 index 0000000..5e69bab --- /dev/null +++ b/docs/release_versioning.md @@ -0,0 +1,7 @@ +# Versioning & Release + +- Fichier `VERSION` et `CHANGELOG.md` à jour à chaque modification significative. +- Tags Git: + - `dev`: pointe sur la tête de la branche `dev` (ne pas utiliser en Docker) + - Tags de CI: `dev-test*` selon besoin +- Politique Docker: images taggées par `DOCKER_TAG` uniquement. diff --git a/docs/scripts.md b/docs/scripts.md new file mode 100644 index 0000000..1b7fe8d --- /dev/null +++ b/docs/scripts.md @@ -0,0 +1,16 @@ +# Scripts + +## build_and_push.sh + +- Usage: `scripts/build_and_push.sh ` (obligatoire) +- Construit et pousse chaque submodule avec `Dockerfile`. + +## tag.sh + +- Usage: `scripts/tag.sh [TAG_NAME]` (défaut `dev-test`) +- Pose le tag sur le dépôt racine et tous les submodules. + +## commit_tag_env.sh + +- Usage: `scripts/commit_tag_env.sh ` +- Crée/checkout une branche du même nom et écrit `.ci/tag.env`. diff --git a/docs/submodules.md b/docs/submodules.md new file mode 100644 index 0000000..74d079f --- /dev/null +++ b/docs/submodules.md @@ -0,0 +1,11 @@ +# Submodules + +## Déclaration + +- Chaque sous-dépôt est déclaré dans `.gitmodules` avec `path`, `url`, `branch`. + +## Bonnes pratiques + +- Exécuter `git submodule sync --recursive` après modification de `.gitmodules`. +- Utiliser `git submodule update --init --recursive` pour initialiser. +- Éviter les chemins ambigus; respecter `modules/`, `deploy/`, `projects//`.