anchorage_layer_simple/fixKnowledge/docker-services-boot-startup.md

Fix: Amélioration du démarrage automatique des services Docker (bitcoind et mempool)

Auteur : Équipe 4NK Date : 2026-01-28 Version : 1.0

Problème identifié

Lors du redémarrage de la machine, les services Docker (bitcoind et mempool) ne démarraient pas automatiquement ou dans le bon ordre, causant :

• Le conteneur bitcoin-signet-instance était arrêté après un reboot
• Le mempool API était unhealthy car il ne pouvait pas se connecter à bitcoind
• Aucune politique de redémarrage automatique pour le conteneur bitcoind
• Le script de redémarrage redémarrait mempool avant bitcoind, causant des erreurs de connexion

Symptômes

• Après un reboot, bitcoin-signet-instance était arrêté (status: Exited)
• Le mempool API était unhealthy avec erreurs connect ECONNREFUSED 172.17.0.1:38332
• Les requêtes vers mempool retournaient 502 Bad Gateway
• Le script restart-services-cron.sh redémarrait mempool avant bitcoind

Impact

• Fonctionnalité : Mempool ne fonctionnait pas après un reboot
• Service : Les ancrages Bitcoin ne pouvaient pas être vérifiés via mempool
• Maintenance : Intervention manuelle requise après chaque reboot

Root causes

1. Pas de restart policy : Le conteneur bitcoin-signet-instance n'avait pas de politique de redémarrage automatique (restart: no)
2. Ordre de démarrage incorrect : Le script redémarrait mempool avant bitcoind, causant des erreurs de connexion
3. Pas d'attente de disponibilité : Le script ne vérifiait pas que bitcoind était prêt avant de démarrer mempool
4. Pas de script de démarrage au boot : Aucun mécanisme pour démarrer automatiquement les services Docker au boot

Correctifs appliqués

1. Configuration de la restart policy pour bitcoind

Action : Configuration de la politique de redémarrage automatique pour le conteneur bitcoind

docker update --restart=always bitcoin-signet-instance

Résultat : Le conteneur redémarre automatiquement en cas d'arrêt ou après un reboot

2. Amélioration du script restart-services-cron.sh

Fichier : data/restart-services-cron.sh

Modifications :

• Ordre de démarrage : Bitcoind est maintenant démarré/redémarré AVANT mempool
• Vérification de disponibilité : Attente que le RPC bitcoind soit prêt (max 60s) avant de démarrer mempool
• Gestion des états : Détection si le conteneur est arrêté (start) ou en cours d'exécution (restart)
• Utilisation de up -d : Utilisation de docker compose up -d au lieu de restart pour mempool (démarre si arrêté, redémarre si en cours)

Avant :

# 4. Docker: mempool stack (redémarré avant bitcoind)
# 5. Docker: bitcoind container

Après :

# 4. Docker: bitcoind container (START FIRST)
#   - Attente que RPC soit prêt (max 60s)
# 5. Docker: mempool stack (START AFTER BITCOIND)

3. Création du script start-docker-services.sh

Fichier : data/start-docker-services.sh

Fonctionnalités :

• Démarrage de bitcoind en premier
• Attente que le RPC bitcoind soit prêt (max 120s au boot)
• Démarrage de mempool après bitcoind
• Logging dans data/start-docker-services.log
• Rotation des logs (100 dernières lignes)

Usage : Peut être appelé depuis un service systemd ou un cron @reboot

4. Création du service systemd docker-services.service

Fichier : data/docker-services.service

Configuration :

• Démarre après docker.service et network.target
• Exécute start-docker-services.sh au boot
• Type oneshot avec RemainAfterExit=yes
• Logs via journald

Installation :

sudo cp data/docker-services.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable docker-services
sudo systemctl start docker-services

Modifications

Fichiers modifiés :

• data/restart-services-cron.sh : Amélioration de l'ordre de démarrage et ajout de vérifications

Fichiers créés :

• data/start-docker-services.sh : Script de démarrage au boot
• data/docker-services.service : Service systemd pour démarrage automatique
• fixKnowledge/docker-services-boot-startup.md : Cette documentation

Modalités de déploiement

1. Configurer la restart policy (déjà fait) :

   docker update --restart=always bitcoin-signet-instance
   

2. Installer le service systemd (optionnel mais recommandé) :

   sudo cp data/docker-services.service /etc/systemd/system/
   sudo systemctl daemon-reload
   sudo systemctl enable docker-services
   sudo systemctl start docker-services
   

3. Vérifier le fonctionnement :

   # Vérifier que bitcoind redémarre automatiquement
   docker restart bitcoin-signet-instance
   docker ps | grep bitcoin-signet-instance
   
   # Vérifier que mempool démarre après bitcoind
   sudo systemctl status docker-services
   

4. Tester après un reboot :

   # Après reboot, vérifier
   docker ps | grep -E "(bitcoin|mempool)"
   curl http://localhost:3015/api/v1/blocks/tip/height
   

Modalités d'analyse

• Logs du service systemd :

  sudo journalctl -u docker-services -f
  

• Logs du script :

  tail -f data/start-docker-services.log
  

• Vérification des conteneurs :

  docker ps --format "table {{.Names}}\t{{.Status}}"
  docker inspect bitcoin-signet-instance --format='{{.HostConfig.RestartPolicy.Name}}'
  

• Vérification de la connectivité :

  # Bitcoind RPC
  docker exec bitcoin-signet-instance bitcoin-cli -datadir=/root/.bitcoin getblockchaininfo
  
  # Mempool API
  curl http://localhost:3015/api/v1/blocks/tip/height
  

Evolutions

• Démarrage automatique au boot : Les services Docker démarrent automatiquement après un reboot
• Ordre de démarrage garanti : Bitcoind démarre toujours avant mempool
• Vérification de disponibilité : Attente que bitcoind soit prêt avant de démarrer mempool
• Restart policy : Le conteneur bitcoind redémarre automatiquement en cas d'arrêt
• Meilleure observabilité : Logs détaillés pour le diagnostic

Références

• Documentation existante : features/cron-restart-services-local.md
• Script de redémarrage : data/restart-services-cron.sh
• Script de démarrage : data/start-docker-services.sh