4NK_node/docs/INSTALLATION.md

📦 Guide d'Installation - 4NK Node

Guide complet pour installer et configurer l'infrastructure 4NK Node.

📋 Prérequis

Système

• OS : Linux (Ubuntu 20.04+, Debian 11+, CentOS 8+)
• Architecture : x86_64
• RAM : 4 Go minimum, 8 Go recommandés
• Stockage : 20 Go minimum, 50 Go recommandés
• Réseau : Connexion Internet stable

Logiciels

• Docker : Version 20.10+
• Docker Compose : Version 2.0+
• Git : Version 2.25+
• Bash : Version 4.0+

🚀 Installation

1. Amorçage automatique (recommandé)

Exécuter le script d’amorçage qui installe git, Docker, Docker Compose, Node.js/npm (via nvm, dernière LTS) et ajoute l’utilisateur au groupe docker dès le début.

./scripts/bootstrap.sh
# Se déconnecter/reconnecter ensuite ou `newgrp docker` pour activer le groupe docker

2. Installation de Docker (manuel)

Ubuntu/Debian

# Mettre à jour les paquets
sudo apt update

# Installer les dépendances
sudo apt install -y apt-transport-https ca-certificates curl gnupg lsb-release

# Ajouter la clé GPG Docker
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg

# Ajouter le repository Docker
echo "deb [arch=amd64 signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Installer Docker
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Ajouter l'utilisateur au groupe docker
sudo usermod -aG docker $USER

# Démarrer Docker
sudo systemctl start docker
sudo systemctl enable docker

CentOS/RHEL

# Installer les dépendances
sudo yum install -y yum-utils

# Ajouter le repository Docker
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# Installer Docker
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Démarrer Docker
sudo systemctl start docker
sudo systemctl enable docker

# Ajouter l'utilisateur au groupe docker
sudo usermod -aG docker $USER

3. Configuration SSH (recommandé)

# Générer une clé SSH
ssh-keygen -t ed25519 -f ~/.ssh/id_ed25519_4nk -C "4nk-automation"

# Ajouter à l'agent SSH
ssh-add ~/.ssh/id_ed25519_4nk

# Configurer Git pour utiliser la clé
git config --global core.sshCommand "ssh -i ~/.ssh/id_ed25519_4nk"

# Afficher la clé publique pour GitLab
cat ~/.ssh/id_ed25519_4nk.pub

Ajouter la clé publique à GitLab :

1. Aller sur GitLab > Settings > SSH Keys
2. Coller la clé publique
3. Cliquer sur "Add key"

4. Clonage du repository

# Cloner avec SSH (recommandé)
git clone git@git.4nkweb.com:4nk/4NK_node.git
cd 4NK_node

# Ou avec HTTPS (si SSH non configuré)
# git clone https://git.4nkweb.com/4nk/4NK_node.git
# cd 4NK_node

5. Vérification de l'installation

# Vérifier Docker
docker --version
docker-compose --version

# Vérifier la connectivité GitLab
ssh -T git@git.4nkweb.com

# Vérifier les permissions
ls -la

🔧 Configuration initiale

1. Configuration des Variables d'Environnement

# Créer le fichier d'environnement
cat > .env << EOF
# Configuration 4NK Node
PROJECT_NAME=4NK Node
NETWORK_NAME=4nk_node_btcnet

# Logs
RUST_LOG=debug,bitcoincore_rpc=trace

# Bitcoin
BITCOIN_COOKIE_PATH=/home/bitcoin/.bitcoin/signet/.cookie

# Synchronisation
ENABLE_SYNC_TEST=1

# Ports
TOR_PORTS=9050:9050,9051:9051
BITCOIN_PORTS=38333:38333,18443:18443,29000:29000
BLINDBIT_PORTS=8000:8000
RELAY_1_PORTS=8090:8090,8091:8091
RELAY_2_PORTS=8092:8090,8093:8091
RELAY_3_PORTS=8094:8090,8095:8091
EOF

2. Préparation de l’UI (ihm_client)

# Construire l’UI localement et produire ./ihm_client/dist
chmod +x scripts/build_ui_local.sh
./scripts/build_ui_local.sh

3. Génération des certificats

# Générer les certificats auto-signés et appliquer les bons droits
chmod +x scripts/generate_certs.sh
./scripts/generate_certs.sh

4. Configuration Bitcoin Core

# Vérifier la configuration Bitcoin
cat bitcoin/bitcoin.conf

# Modifier si nécessaire
nano bitcoin/bitcoin.conf

Configuration recommandée :

# Configuration Bitcoin Core Signet
signet=1
rpcuser=bitcoin
rpcpassword=your_secure_password
rpcbind=0.0.0.0
rpcallowip=172.19.0.0/16
zmqpubrawblock=tcp://0.0.0.0:29000
zmqpubrawtx=tcp://0.0.0.0:29000
txindex=1
server=1
listen=1

5. Configuration Tor (option bridges)

Si votre réseau nécessite des bridges obfs4, ajoutez-les dans tor/torrc :

UseBridges 1
ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy
# Exemple
Bridge obfs4 81.64.0.218:6697 53E6469DC06BED50543AED0311D66082F4B66676 cert=zOKy+MnZ4wWbKcENcyaElPu62PEaXdE/c802ssuzCIDa2aIC1+J4LyfPhAwSiLaAo/I/bg iat-mode=0
Bridge obfs4 198.98.53.149:443 886CA31F71272FC8B3808C601FA3ABB8A2905DB4 cert=D+zypuFdMpP8riBUbInxIguzqClR0JKkP1DbkKz5es1+OP2Fao8jiXyM+B/+DYA2ZFy6UA iat-mode=0

Puis reconstruire et (re)démarrer :

sudo docker compose build tor
sudo docker compose up -d tor

6. Configuration Blindbit

# Vérifier la configuration Blindbit
cat blindbit/blindbit.toml

# Modifier si nécessaire
nano blindbit/blindbit.toml

Configuration recommandée :

# Configuration Blindbit
host = "0.0.0.0:8000"
chain = "signet"
rpc_endpoint = "http://bitcoin:18443"
cookie_path = "/home/bitcoin/.bitcoin/signet/.cookie"
sync_start_height = 1
max_parallel_tweak_computations = 4
max_parallel_requests = 4

7. Configuration des Relais

# Vérifier les configurations des relais
ls -la sdk_relay/.conf.docker.*

# Modifier si nécessaire
nano sdk_relay/.conf.docker.relay1
nano sdk_relay/.conf.docker.relay2
nano sdk_relay/.conf.docker.relay3

Configuration recommandée pour chaque relay :

core_url=http://bitcoin:18443
core_wallet=relay_wallet
ws_url=0.0.0.0:8090
wallet_name=relay_wallet.json
network=signet
blindbit_url=http://blindbit:8000
zmq_url=tcp://bitcoin:29000
data_dir=.4nk
cookie_path=/home/bitcoin/.4nk/bitcoin.cookie
dev_mode=true
standalone=false
relay_id=relay-1  # Changer pour chaque relay

🚀 Démarrage

1. Démarrage Complet

# Démarrer l’infrastructure (reverse proxy inclus)
sudo docker compose up -d --build

# Vérifier le statut
docker ps

2. Démarrage Séquentiel (Debug)

# Démarrer Tor (si utilisé)
sudo docker compose up -d tor

# Démarrer Bitcoin Core
sudo docker compose up -d bitcoin

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

# Démarrer Blindbit
sudo docker compose up -d blindbit

# Démarrer les relais et le reverse proxy
sudo docker compose up -d sdk_relay_1 sdk_relay_2 sdk_relay_3 reverse_proxy

3. Vérification du Démarrage

# Vérifier tous les services
docker ps

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

# Vérifier l’accès public
curl -kI https://<IP_VM>/
curl -kI https://<IP_VM>/api/

🧪 Tests Post-Installation

1. Tests de Connectivité

# Test de base
./test_final_sync.sh

# Test de synchronisation
./test_sync_logs.sh

# Test des messages WebSocket
python3 test_websocket_messages.py

2. Tests de Performance

# Vérifier l'utilisation des ressources
docker stats

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

# Monitoring de la synchronisation
./monitor_sync.sh

3. Tests de Sécurité

# Vérifier les ports exposés
netstat -tlnp | grep -E "(18443|8000|9050|8090)"

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

🔧 Configuration Avancée

1. Configuration Réseau

# Créer un réseau Docker personnalisé
docker network create 4nk-network --subnet=172.20.0.0/16

# Modifier docker-compose.yml
sed -i 's/4nk_default/4nk-network/g' docker-compose.yml

2. Configuration SSL/TLS

# Générer un certificat auto-signé
openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 365 -nodes

# Configurer nginx comme proxy SSL
cat > nginx.conf << EOF
server {
    listen 443 ssl;
    server_name your-domain.com;

    ssl_certificate cert.pem;
    ssl_certificate_key key.pem;

    location / {
        proxy_pass http://localhost:8090;
        proxy_http_version 1.1;
        proxy_set_header Upgrade \$http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host \$host;
    }
}
EOF

3. 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

🚨 Dépannage

Problèmes Courants

1. Docker Non Installé

# Vérifier l'installation Docker
docker --version

# Si non installé, suivre les étapes d'installation ci-dessus

2. Permissions Docker

# Vérifier les permissions
docker ps

# Si erreur de permission
sudo usermod -aG docker $USER
newgrp docker

3. Ports Déjà Utilisés

# Vérifier les ports utilisés
sudo netstat -tlnp | grep -E "(18443|8000|9050|8090)"

# Arrêter les services conflictuels
sudo docker-compose down

4. Problèmes de Synchronisation Bitcoin

# Vérifier les logs Bitcoin
docker logs bitcoin-signet

# Vérifier l'espace disque
df -h

# Redémarrer Bitcoin Core
docker restart bitcoin-signet

Logs Utiles

# 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"

📊 Monitoring

1. Monitoring de Base

# Statut des conteneurs
docker ps

# Utilisation des ressources
docker stats

# Espace disque
docker system df

2. Monitoring Avancé

# Surveillance de la synchronisation
./monitor_sync.sh

# Monitoring en continu
while true; do
    echo "=== $(date) ==="
    docker stats --no-stream | grep -E "(sdk_relay|bitcoin)"
    sleep 30
done

3. Alertes

# Script d'alerte simple
cat > monitor_alert.sh << 'EOF'
#!/bin/bash
if ! docker ps | grep -q "bitcoin-signet.*Up"; then
    echo "ALERTE: Bitcoin Core n'est pas en cours d'exécution!"
    # Ajouter notification (email, Slack, etc.)
fi
EOF

chmod +x monitor_alert.sh

🔄 Mise à Jour

1. Mise à Jour de l'Infrastructure

# Sauvegarder la configuration
cp -r . ../4NK_node_backup_$(date +%Y%m%d)

# Mettre à jour le code
git pull origin main

# Redémarrer les services
./restart_4nk_node.sh

2. Mise à Jour de Docker

# Mettre à jour Docker
sudo apt update
sudo apt upgrade docker-ce docker-ce-cli containerd.io

# Redémarrer Docker
sudo systemctl restart docker

3. Mise à Jour des Images

# Reconstruire les images
docker-compose build --no-cache

# Redémarrer les services
docker-compose up -d

📝 Checklist d'Installation

• Docker installé et configuré
• Docker Compose installé
• Clé SSH configurée pour GitLab
• Repository cloné
• Variables d'environnement configurées
• Configurations Bitcoin Core vérifiées
• Configurations Blindbit vérifiées
• Configurations des relais vérifiées
• Services démarrés avec succès
• Tests de connectivité passés
• Tests de synchronisation passés
• Monitoring configuré
• Pare-feu configuré (optionnel)
• SSL/TLS configuré (optionnel)

🎉 Installation Terminée

Félicitations ! L'infrastructure 4NK Node est maintenant installée et configurée.

Prochaines étapes :

1. Consulter le Guide d'Utilisation
2. Configurer les Nœuds Externes
3. Tester la Synchronisation
4. Configurer le Monitoring

---