4NK_template/docs/USAGE.md

# 📖 Guide d'Utilisation - 4NK Node

Guide complet pour utiliser l'infrastructure 4NK Node au quotidien.

## 🚀 Démarrage Quotidien

### 1. Démarrage Rapide

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

# Vérifier le statut
docker ps
```

### 2. Démarrage Séquentiel

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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é

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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é

```bash
# 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

```bash
# 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é

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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é

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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 4NK Node - Utilisation optimale !**