4NK_template/docs/USAGE.md

📖 Guide d'Utilisation - <PROJECT_NAME>

Ce document est un modèle générique. Remplacez <PROJECT_NAME> et adaptez les commandes/chemins à votre projet.

Guide complet pour utiliser l'infrastructure <PROJECT_NAME> au quotidien.

🚀 Démarrage Quotidien

1. Démarrage Rapide

# Démarrer tous les services
./restart_4nk_node.sh

# Vérifier le statut
docker ps

2. Démarrage Séquentiel

# Démarrer Tor
./restart_4nk_node.sh -t

# Démarrer Bitcoin Core
./restart_4nk_node.sh -b

# Attendre la synchronisation Bitcoin
echo "Attendre la synchronisation Bitcoin (10-30 minutes)..."
docker logs bitcoin-signet | grep "progress"

# Démarrer Blindbit
./restart_4nk_node.sh -l

# Démarrer les relais
./restart_4nk_node.sh -r

3. Vérification du Démarrage

# Vérifier tous les services
docker ps

# Vérifier les logs
docker-compose logs --tail=50

# Vérifier la connectivité
./test_final_sync.sh

🔧 Opérations Quotidiennes

1. Surveillance des Services

# Statut des services
docker ps

# Logs en temps réel
docker-compose logs -f

# Utilisation des ressources
docker stats

# Espace disque
docker system df

2. Monitoring de la Synchronisation

# Surveillance de la synchronisation
./monitor_sync.sh

# Test de synchronisation
./test_sync_logs.sh

# Test des messages WebSocket
python3 test_websocket_messages.py

3. Gestion des Logs

# Logs de tous les services
docker-compose logs -f

# Logs d'un service spécifique
docker logs bitcoin-signet
docker logs blindbit-oracle
docker logs sdk_relay_1

# Logs avec timestamps
docker-compose logs -t

# Logs depuis une date
docker-compose logs --since="2024-01-01T00:00:00"

# Logs des 100 dernières lignes
docker-compose logs --tail=100

🌐 Utilisation du Réseau de Relais

1. Configuration des Relais

L'infrastructure utilise 3 relais locaux :

Relay	Port WebSocket	Port HTTP	Configuration
Relay 1	8090	8091	sdk_relay/.conf.docker.relay1
Relay 2	8092	8093	sdk_relay/.conf.docker.relay2
Relay 3	8094	8095	sdk_relay/.conf.docker.relay3

2. Test de Connectivité des Relais

# Test de connectivité de base
./test_final_sync.sh

# Test de synchronisation
./test_sync_logs.sh

# Test des messages WebSocket
python3 test_websocket_messages.py

# Test de charge
python3 test_websocket_messages.py --load-test

3. Surveillance de la Synchronisation

# Surveillance en temps réel
./monitor_sync.sh

# Test de synchronisation forcé
./test_sync_logs.sh force

# Test de synchronisation en continu
./test_sync_logs.sh continuous

🔗 Connexion aux Services

1. Bitcoin Core RPC

# Connexion via curl
curl -u bitcoin:your_password --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "getblockchaininfo", "params": []}' -H 'content-type: text/plain;' http://localhost:18443/

# Connexion via bitcoin-cli
docker exec bitcoin-signet bitcoin-cli -signet getblockchaininfo

# Vérifier la synchronisation
docker exec bitcoin-signet bitcoin-cli -signet getblockchaininfo | jq '.verificationprogress'

2. Blindbit API

# Test de connectivité
curl -s http://localhost:8000/

# Vérifier le statut
curl -s http://localhost:8000/status

# Obtenir des filtres
curl -s http://localhost:8000/filters

3. sdk_relay WebSocket

# Test de connectivité WebSocket
curl -v -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Key: test" http://localhost:8090/

# Test avec wscat (si installé)
wscat -c ws://localhost:8090

# Test avec Python
python3 test_websocket_messages.py

🧪 Tests et Validation

1. Tests de Base

# Test de connectivité complet
./test_final_sync.sh

# Test de synchronisation
./test_sync_logs.sh

# Test des messages
./test_messages.sh

# Test des 3 relais
./test_3_relays.sh

2. Tests de Performance

# Test de charge WebSocket
for i in {1..10}; do
    python3 test_websocket_messages.py &
done
wait

# Test de connectivité multiple
netstat -tlnp | grep -E "(8090|8092|8094)"

# Test de performance
docker stats --no-stream

3. Tests de Sécurité

# Vérifier les ports exposés
netstat -tuln | grep -E "(8090|8092|8094)"

# Vérifier les logs d'accès
docker logs sdk_relay_1 | grep -E "(ERROR|WARN)" | tail -20

# Vérifier l'utilisation des ressources
docker stats --no-stream | grep sdk_relay

🔧 Configuration et Maintenance

1. Modification de Configuration

# Modifier la configuration Bitcoin Core
sudo docker-compose down
nano bitcoin/bitcoin.conf
sudo docker-compose up -d bitcoin

# Modifier la configuration Blindbit
nano blindbit/blindbit.toml
sudo docker-compose restart blindbit

# Modifier la configuration des relais
nano sdk_relay/.conf.docker.relay1
sudo docker-compose restart sdk_relay_1

2. Redémarrage des Services

# Redémarrage complet
./restart_4nk_node.sh

# Redémarrage d'un service spécifique
docker-compose restart bitcoin
docker-compose restart blindbit
docker-compose restart sdk_relay_1

# Redémarrage avec reconstruction
docker-compose down
docker-compose build --no-cache
docker-compose up -d

3. Sauvegarde et Restauration

# Sauvegarde des données
docker exec bitcoin-signet tar czf /tmp/bitcoin-backup.tar.gz /home/bitcoin/.bitcoin
docker cp bitcoin-signet:/tmp/bitcoin-backup.tar.gz ./backup/

# Sauvegarde des configurations
tar czf config-backup.tar.gz sdk_relay/.conf* external_nodes.conf

# Restauration
docker cp ./backup/bitcoin-backup.tar.gz bitcoin-signet:/tmp/
docker exec bitcoin-signet tar xzf /tmp/bitcoin-backup.tar.gz -C /

🌐 Gestion des Nœuds Externes

1. Ajout de Nœuds Externes

# Ajouter un nœud externe
./add_external_node.sh add external-relay-1 external-relay-1.example.com:8090

# Lister les nœuds configurés
./add_external_node.sh list

# Tester la connectivité
./add_external_node.sh test external-relay-1

# Supprimer un nœud
./add_external_node.sh remove external-relay-1

2. Configuration Multi-Sites

# Site principal
./add_external_node.sh add site-paris-1 paris-relay-1.4nk.net:8090
./add_external_node.sh add site-paris-2 paris-relay-2.4nk.net:8090

# Site secondaire
./add_external_node.sh add site-lyon-1 lyon-relay-1.4nk.net:8090
./add_external_node.sh add site-lyon-2 lyon-relay-2.4nk.net:8090

# Site de backup
./add_external_node.sh add backup-1 backup-relay-1.4nk.net:8090

3. Test d'Intégration

# Test d'intégration complet
./test_integration_dev3.sh

# Test de connectivité dev3
python3 test_dev3_simple.py

# Test de connectivité avancé
python3 test_dev3_connectivity.py

📊 Monitoring et Alertes

1. Monitoring de Base

# Surveillance de la synchronisation
./monitor_sync.sh

# Monitoring en continu
while true; do
    echo "=== $(date) ==="
    docker stats --no-stream | grep -E "(sdk_relay|bitcoin)"
    echo "WebSocket connections:"
    netstat -an | grep :8090 | wc -l
    sleep 30
done

2. Monitoring Avancé

# Script de monitoring complet
cat > monitor_advanced.sh << 'EOF'
#!/bin/bash
while true; do
    clear
    echo "=== 4NK Node Monitoring ==="
    echo "Date: $(date)"
    echo ""

    echo "Services:"
    docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"
    echo ""

    echo "Ressources:"
    docker stats --no-stream | grep -E "(sdk_relay|bitcoin|blindbit)"
    echo ""

    echo "Connexions WebSocket:"
    netstat -an | grep :8090 | wc -l
    echo ""

    echo "Espace disque:"
    df -h | grep -E "(bitcoin|blindbit)"
    echo ""

    sleep 60
done
EOF

chmod +x monitor_advanced.sh
./monitor_advanced.sh

3. Alertes Automatiques

# Script d'alerte simple
cat > alert_monitor.sh << 'EOF'
#!/bin/bash

# Vérifier Bitcoin Core
if ! docker ps | grep -q "bitcoin-signet.*Up"; then
    echo "ALERTE: Bitcoin Core n'est pas en cours d'exécution!"
fi

# Vérifier les relais
for i in {1..3}; do
    if ! docker ps | grep -q "sdk_relay_$i.*Up"; then
        echo "ALERTE: Relay $i n'est pas en cours d'exécution!"
    fi
done

# Vérifier l'espace disque
if [ $(df / | awk 'NR==2 {print $5}' | sed 's/%//') -gt 90 ]; then
    echo "ALERTE: Espace disque faible!"
fi
EOF

chmod +x alert_monitor.sh

# Ajouter au cron pour surveillance automatique
echo "*/5 * * * * /path/to/alert_monitor.sh" | crontab -

🔒 Sécurité

1. Vérification de Sécurité

# Vérifier les ports exposés
netstat -tuln | grep -E "(8090|8092|8094)"

# Vérifier les permissions
ls -la sdk_relay/.conf*
ls -la bitcoin/bitcoin.conf
ls -la blindbit/blindbit.toml

# Vérifier les logs de sécurité
docker logs sdk_relay_1 | grep -E "(ERROR|WARN|SECURITY)" | tail -20

2. Configuration de Pare-feu

# Autoriser seulement les ports nécessaires
sudo ufw allow 18443/tcp  # Bitcoin Core RPC
sudo ufw allow 8090/tcp   # sdk_relay WebSocket
sudo ufw allow 8000/tcp   # Blindbit API
sudo ufw enable

# Vérifier les règles
sudo ufw status numbered

3. Rotation des Logs

# Configuration de rotation des logs
cat > /etc/logrotate.d/4nk-node << EOF
/var/lib/docker/containers/*/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}
EOF

🚨 Dépannage

1. Problèmes Courants

Service Ne Démarre Pas

# Vérifier les logs
docker logs <service_name>

# Vérifier la configuration
docker exec <service_name> cat /path/to/config

# Redémarrer le service
docker restart <service_name>

Problèmes de Connectivité

# Tester la connectivité réseau
docker exec <service_name> ping <target>

# Vérifier la résolution DNS
docker exec <service_name> nslookup <target>

# Tester les ports
docker exec <service_name> nc -z <target> <port>

Problèmes de Synchronisation

# Vérifier les logs de synchronisation
docker logs sdk_relay_1 | grep -E "(Sync|Relay|Mesh)"

# Forcer la synchronisation
docker restart sdk_relay_1 sdk_relay_2 sdk_relay_3

# Vérifier la connectivité entre relais
./test_sync_logs.sh force

2. Logs de Debug

# Logs détaillés
docker-compose logs -f --tail=100

# Logs d'un service spécifique
docker logs <service_name> -f

# Logs avec timestamps
docker-compose logs -t

# Logs depuis une date
docker-compose logs --since="2024-01-01T00:00:00"

3. Outils de Debug

# Debug du container sdk_relay
./sdk_relay/debug_container.sh

# Test du healthcheck
./sdk_relay/test_healthcheck.sh

# Test de connectivité
./sdk_relay/test_connectivity.sh

# Test simple
./sdk_relay/test_simple.sh

📈 Performance

1. Optimisation

# Limiter l'utilisation CPU
docker-compose up -d --scale bitcoin=1

# Optimiser la mémoire
docker stats --no-stream | grep sdk_relay

# Nettoyer l'espace disque
docker system prune -f

2. Monitoring de Performance

# Surveillance des ressources
docker stats

# Surveillance des connexions
netstat -an | grep :8090 | wc -l

# Surveillance de l'espace disque
df -h

3. Tests de Charge

# Test de charge simple
for i in {1..50}; do
    python3 test_websocket_messages.py &
    sleep 0.1
done
wait

# Test de charge avancé
python3 test_websocket_messages.py --load-test --duration=300

🔄 Maintenance

1. Sauvegarde Régulière

# Script de sauvegarde automatique
cat > backup_4nk.sh << 'EOF'
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
BACKUP_DIR="/backup/4nk_node_$DATE"

mkdir -p $BACKUP_DIR

# Sauvegarder les configurations
cp -r sdk_relay/.conf* $BACKUP_DIR/
cp external_nodes.conf $BACKUP_DIR/

# Sauvegarder les données Bitcoin
docker exec bitcoin-signet tar czf /tmp/bitcoin-backup.tar.gz /home/bitcoin/.bitcoin
docker cp bitcoin-signet:/tmp/bitcoin-backup.tar.gz $BACKUP_DIR/

echo "Sauvegarde terminée: $BACKUP_DIR"
EOF

chmod +x backup_4nk.sh

2. Mise à Jour

# Mise à jour de l'infrastructure
git pull origin main
./restart_4nk_node.sh

# Mise à jour des images
docker-compose build --no-cache
docker-compose up -d

3. Nettoyage

# Nettoyer les conteneurs arrêtés
docker container prune -f

# Nettoyer les images non utilisées
docker image prune -f

# Nettoyer les volumes non utilisés
docker volume prune -f

# Nettoyer tout
docker system prune -a -f

📝 Checklist Quotidienne

• Services démarrés et fonctionnels
• Bitcoin Core synchronisé
• Relais connectés et synchronisés
• Tests de connectivité passés
• Logs vérifiés (pas d'erreurs critiques)
• Ressources système OK
• Sauvegarde effectuée (si nécessaire)
• Monitoring actif

🎯 Commandes Rapides

# Démarrage rapide
./restart_4nk_node.sh

# Statut des services
docker ps

# Logs en temps réel
docker-compose logs -f

# Test de connectivité
./test_final_sync.sh

# Surveillance
./monitor_sync.sh

# Arrêt propre
docker-compose down

---

✨ Infrastructure <PROJECT_NAME> - Utilisation optimale !