4NK_env/IA_agents/blindbit-oracle-deployment.md

BlindBit Oracle - Déploiement et Configuration

📋 Vue d'ensemble

BlindBit Oracle est un service critique de la chaîne blockchain LeCoffre Node. Ce document décrit son déploiement, sa configuration et sa correction du bug d'écoute.

🐛 Bug Corrigé

Problème Identifié

L'application BlindBit Oracle ignorait la configuration host du fichier TOML et écoutait toujours sur 127.0.0.1:8000 en dur dans le code, rendant le service inaccessible depuis l'extérieur du conteneur.

Solution Appliquée

1. Analyse du code source : Identification du problème dans /src/common/vars.go
2. Correction du code : Ajout d'un log de débogage dans /src/common/config.go
3. Construction d'une nouvelle image : git.4nkweb.com/4nk/blindbit-oracle:fixed-source
4. Test de validation : Confirmation que l'application écoute maintenant sur 0.0.0.0:8000

🏗️ Architecture

Position dans la Chaîne

bitcoin (healthy) → blindbit-oracle → sdk_relay

Ports et Services

Service	Port Interne	Port Externe	Protocole
BlindBit Oracle	8000	8000	HTTP
gRPC Server	50051	-	gRPC (interne)

📁 Configuration Centralisée

Fichier de Configuration

• Chemin : /home/debian/4NK_env/confs/lecoffre_node/blindbit-oracle/blindbit.toml
• Montage : /tmp/blindbit.toml:ro → /root/.blindbit-oracle/blindbit.toml

Configuration Type

# Configuration Blindbit Oracle
host = "0.0.0.0:8000"
chain = "signet"
rpc_endpoint = "http://bitcoin:38332"
cookie_path = "/home/bitcoin/.bitcoin/signet/.cookie"
rpc_user = ""
rpc_pass = ""
sync_start_height = 1

# Performance
max_parallel_tweak_computations = 4
max_parallel_requests = 4

# Index
tweaks_only = 0
tweaks_full_basic = 1
tweaks_full_with_dust_filter = 1
tweaks_cut_through_with_dust_filter = 1

📊 Logs Centralisés

Répertoire de Logs

• Chemin : /home/debian/4NK_env/logs/blindbit/
• Montage : /var/log/blindbit

Fichiers de Logs

• Logs d'application
• Logs de synchronisation
• Logs d'erreurs

🐳 Docker Compose

Service Definition

blindbit:
  image: git.4nkweb.com/4nk/blindbit-oracle:fixed-source
  container_name: blindbit-oracle
  depends_on:
    bitcoin:
      condition: service_healthy
  volumes:
    - blindbit_data:/root/.blindbit-oracle
    - /home/debian/4NK_env/confs/lecoffre_node/blindbit-oracle/blindbit.toml:/tmp/blindbit.toml:ro
    - bitcoin_data:/home/bitcoin/.bitcoin
    - /home/debian/4NK_env/logs/blindbit:/var/log/blindbit
    - /home/debian/4NK_env/scripts/lecoffre_node/healthchecks:/scripts/healthchecks:ro
  entrypoint: >
    sh -c "mkdir -p /root/.blindbit-oracle &&
          if [ ! -f /root/.blindbit-oracle/blindbit.toml ]; then
            cp /tmp/blindbit.toml /root/.blindbit-oracle/blindbit.toml;
          fi &&
          echo 'Starting BlindBit Oracle with corrected host binding...' &&
          exec ./main -datadir /root/.blindbit-oracle"
  networks:
    btcnet:
      aliases:
        - blindbit
  ports:
    - "0.0.0.0:8000:8000"
  healthcheck:
    test: ["CMD", "sh", "/scripts/healthchecks/blindbit-progress.sh"]
    interval: 10s
    timeout: 5s
    retries: 60
    start_period: 180s
  restart: unless-stopped

🔍 Healthcheck

Script de Healthcheck

• Chemin : /scripts/healthchecks/blindbit-progress.sh
• Fonction : Vérification de la synchronisation et de l'API

Critères de Santé

1. Synchronisation : Headers synchronisés avec Bitcoin
2. API : Endpoint /tweaks/1 accessible
3. Port : Service écoute sur 0.0.0.0:8000

🚀 Démarrage

Ordre de Démarrage

1. bitcoin doit être healthy
2. blindbit-oracle démarre automatiquement
3. sdk_relay attend que blindbit soit healthy

Commandes de Démarrage

# Démarrage complet (recommandé)
./scripts/lecoffre_node/start.sh

# Démarrage spécifique
docker compose --env-file /home/debian/4NK_env/.env.master up -d blindbit

🔧 Maintenance

Logs de Surveillance

# Logs en temps réel
docker logs -f blindbit-oracle

# Logs avec progression
./scripts/lecoffre_node/logs-with-progress.sh blindbit

Redémarrage

# Redémarrage du service
docker compose --env-file /home/debian/4NK_env/.env.master restart blindbit

# Redémarrage avec reconstruction
docker compose --env-file /home/debian/4NK_env/.env.master up -d --force-recreate blindbit

🧪 Tests

Test de l'API

# Test basique
curl http://localhost:8000/tweaks/1

# Test avec code de retour
curl -s -o /dev/null -w "HTTP Code: %{http_code}\n" http://localhost:8000/tweaks/1

Vérification des Ports

# Ports d'écoute
docker exec blindbit-oracle netstat -tlnp

# Vérification de la configuration
docker exec blindbit-oracle cat /root/.blindbit-oracle/blindbit.toml

🚨 Dépannage

Problèmes Courants

Service non accessible (HTTP 000)

• Cause : Ancienne image sans correction du bug
• Solution : Utiliser l'image fixed-source

Configuration non chargée

• Cause : Fichier de configuration manquant ou mal monté
• Solution : Vérifier le montage dans docker-compose.yml

Synchronisation lente

• Cause : Première synchronisation ou réseau lent
• Solution : Attendre la fin de la synchronisation (visible dans les logs)

Logs de Diagnostic

# Logs de configuration
docker logs blindbit-oracle | grep -i "host configuration"

# Logs de synchronisation
docker logs blindbit-oracle | grep -i "sync"

# Logs d'erreurs
docker logs blindbit-oracle | grep -i "error"

📈 Monitoring

Métriques Importantes

1. Synchronisation : Progression de la synchronisation avec Bitcoin
2. API Response Time : Temps de réponse des endpoints
3. Memory Usage : Utilisation mémoire du service
4. Disk Usage : Espace disque utilisé par les données

Dashboards Grafana

• BlindBit Oracle Overview : Vue d'ensemble du service
• Synchronization Progress : Progression de synchronisation
• API Performance : Performances de l'API

🔄 Mise à Jour

Procédure de Mise à Jour

1. Arrêt du service : docker compose stop blindbit
2. Mise à jour de l'image : docker pull git.4nkweb.com/4nk/blindbit-oracle:fixed-source
3. Redémarrage : docker compose up -d blindbit
4. Vérification : Tests de l'API et des logs

Sauvegarde des Données

# Sauvegarde des données BlindBit
./scripts/lecoffre_node/backup-data.sh

# Restauration des données
./scripts/lecoffre_node/restore-data.sh

📚 Références

Code Source

• Repository : https://github.com/setavenger/blindbit-oracle
• Image Corrigée : git.4nkweb.com/4nk/blindbit-oracle:fixed-source

Documentation Technique

• Configuration TOML : /home/debian/4NK_env/confs/lecoffre_node/blindbit-oracle/blindbit.toml
• Logs : /home/debian/4NK_env/logs/blindbit/
• Healthcheck : /home/debian/4NK_env/scripts/lecoffre_node/healthchecks/blindbit-progress.sh

---

Document créé le 2025-09-25 Version : 1.0 Usage : Obligatoire pour le déploiement de BlindBit Oracle Mise à jour : Après chaque modification de configuration ou d'image