lecoffre_node/docs/retours_experience/REX_STARTUP_SEQUENCE_IMPROVEMENTS.md

Retour d'Expérience : Améliorations de la séquence de démarrage

Problème initial

• Erreur : dependency failed to start: container sdk_relay is unhealthy
• Cause : Le service sdk_relay bloquait sur le scan de blocs pendant le démarrage
• Impact : Les services dépendants ne pouvaient pas démarrer

Diagnostic effectué

1. Analyse du code sdk_relay

// Problème identifié dans main.rs
let current_tip = get_blockchain_tip().await?;
let last_scan = get_last_scan().await?;

// ❌ Cette ligne bloquait le démarrage
scan_blocks(current_tip - last_scan, &config.blindbit_url).await?;

// Les serveurs WebSocket et HTTP étaient lancés APRÈS
let listener = TcpListener::bind(config.ws_url).await;
tokio::spawn(start_health_server(8091));

2. Impact sur les services dépendants

• ihm_client : Dépend de sdk_relay healthy
• lecoffre-back : Dépend de sdk_relay healthy
• lecoffre-front : Dépend de lecoffre-back healthy

Solutions implémentées

1. Amélioration des healthchecks

# docker-compose.yml
services:
  sdk_relay:
    healthcheck:
      test: ["CMD", "sh", "-c", "curl -f http://localhost:8091/ | grep -q '\"status\":\"ok\"'"]
      interval: 15s
      timeout: 10s
      retries: 5
      start_period: 60s  # ⭐ Temps d'attente avant les tests

2. Variables d'environnement pour le démarrage

environment:
  - SDK_RELAY_SCAN_TIMEOUT=300
  - SDK_RELAY_STARTUP_MODE=async

3. Dépendances conditionnelles

services:
  ihm_client:
    depends_on:
      sdk_relay:
        condition: service_healthy  # ⭐ Attendre que sdk_relay soit healthy

  lecoffre-back:
    depends_on:
      sdk_relay:
        condition: service_healthy

4. Script de démarrage intelligent

#!/bin/bash
# startup-sequence.sh

# Validation des dépendances externes
validate_external_dependencies() {
    echo "Vérification des dépendances externes..."

    # Test dev3.4nkweb.com:9090
    timeout 5 bash -c "</dev/tcp/dev3.4nkweb.com/9090" || {
        echo "❌ dev3.4nkweb.com:9090 inaccessible"
        return 1
    }

    # Test https://dev4.4nkweb.com/lecoffre
    curl -f -s https://dev4.4nkweb.com/lecoffre >/dev/null || {
        echo "❌ https://dev4.4nkweb.com/lecoffre inaccessible"
        return 1
    }

    echo "✅ Toutes les dépendances externes sont accessibles"
    return 0
}

# Démarrage des services
start_services() {
    validate_external_dependencies || exit 1
    docker compose up -d
    wait_for_services_healthy
}

Améliorations apportées

1. Healthchecks robustes

• Tests réels : Vérification du endpoint /health au lieu de simples tests de port
• Timeouts appropriés : start_period pour laisser le temps au service de démarrer
• Retry logic : Plusieurs tentatives avant de marquer comme unhealthy

2. Gestion des dépendances

• Dépendances conditionnelles : condition: service_healthy
• Ordre de démarrage : Services critiques en premier
• Validation externe : Vérification des services distants

3. Monitoring et debugging

• Logs colorés : Fonctions de logging avec couleurs
• Validation préalable : Tests de connectivité avant démarrage
• Restart intelligent : Arrêt des services dépendants avant redémarrage

Scripts créés

startup-sequence.sh

#!/bin/bash
# Script de démarrage intelligent avec validation

# Fonctions de logging
log() { echo -e "\033[1;34m[INFO]\033[0m $1"; }
log_success() { echo -e "\033[1;32m[SUCCESS]\033[0m $1"; }
log_warning() { echo -e "\033[1;33m[WARNING]\033[0m $1"; }
log_error() { echo -e "\033[1;31m[ERROR]\033[0m $1"; }

# Validation des dépendances externes
validate_external_dependencies() {
    log "Vérification des dépendances externes..."

    # Test signer distant
    timeout 5 bash -c "</dev/tcp/dev3.4nkweb.com/9090" || {
        log_error "dev3.4nkweb.com:9090 inaccessible"
        return 1
    }

    # Test frontend
    curl -f -s https://dev4.4nkweb.com/lecoffre >/dev/null || {
        log_error "https://dev4.4nkweb.com/lecoffre inaccessible"
        return 1
    }

    log_success "Toutes les dépendances externes sont accessibles"
    return 0
}

# Démarrage des services
start_services() {
    validate_external_dependencies || exit 1
    docker compose up -d
    wait_for_services_healthy
}

# Redémarrage intelligent
restart_services() {
    log "Arrêt des services dépendants..."
    docker compose stop lecoffre-back lecoffre-front ihm_client

    log "Attente des dépendances externes..."
    validate_external_dependencies || exit 1

    log "Redémarrage des services..."
    docker compose up -d
    wait_for_services_healthy
}

Configuration finale

docker-compose.yml optimisé

services:
  sdk_relay:
    image: git.4nkweb.com/4nk/sdk_relay:ext
    healthcheck:
      test: ["CMD", "sh", "-c", "curl -f http://localhost:8091/ | grep -q '\"status\":\"ok\"'"]
      interval: 15s
      timeout: 10s
      retries: 5
      start_period: 60s
    environment:
      - SDK_RELAY_SCAN_TIMEOUT=300
      - SDK_RELAY_STARTUP_MODE=async

  ihm_client:
    depends_on:
      sdk_relay:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:3003/"]
      start_period: 30s

  lecoffre-back:
    depends_on:
      sdk_relay:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/api/v1/health"]
      start_period: 30s

Leçons apprises

1. Healthchecks critiques

• Toujours implémenter des healthchecks robustes
• Tester les endpoints réels plutôt que les ports
• Configurer des timeouts appropriés

2. Gestion des dépendances

• Utiliser condition: service_healthy pour les dépendances
• Valider les services externes avant démarrage
• Implémenter des scripts de redémarrage intelligent

3. Monitoring et debugging

• Logs colorés pour faciliter le debugging
• Validation préalable des dépendances
• Scripts automatisés pour les opérations courantes

Actions préventives

1. Implémenter des healthchecks robustes dès le début
2. Configurer des dépendances conditionnelles
3. Valider les services externes avant démarrage
4. Créer des scripts de démarrage intelligent
5. Documenter les séquences de démarrage

Date

• Créé : 2025-09-20
• Problème résolu : Séquence de démarrage des services
• Impact : Amélioration de la fiabilité et du debugging