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.

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

### 2. Installation de Docker (manuel)

#### Ubuntu/Debian

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

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

```bash
# 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 Gitea
cat ~/.ssh/id_ed25519_4nk.pub
```

**Ajouter la clé publique à Gitea :**
1. Aller sur Gitea > Settings > SSH Keys
2. Coller la clé publique
3. Cliquer sur "Add key"

### 4. Clonage du repository

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

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

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

# Vérifier les permissions
ls -la
```

## 🔧 Configuration initiale

### 1. Configuration des Variables d'Environnement

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

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

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

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

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

**Configuration recommandée :**
```ini
# 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` :

```ini
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 :

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

### 6. Configuration Blindbit

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

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

**Configuration recommandée :**
```toml
# 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

```bash
# 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 :**
```ini
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

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

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

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

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

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

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

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

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

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

## 🚨 Dépannage

### Problèmes Courants

#### 1. Docker Non Installé

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

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

#### 2. Permissions Docker

```bash
# Vérifier les permissions
docker ps

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

#### 3. Ports Déjà Utilisés

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

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

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

## 📊 Monitoring

### 1. Monitoring de Base

```bash
# Statut des conteneurs
docker ps

# Utilisation des ressources
docker stats

# Espace disque
docker system df
```

### 2. Monitoring Avancé

```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)"
    sleep 30
done
```

### 3. Alertes

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

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

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

```bash
# 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](USAGE.md)
2. Configurer les [Nœuds Externes](EXTERNAL_NODES.md)
3. Tester la [Synchronisation](SYNCHRONIZATION.md)
4. Configurer le [Monitoring](PERFORMANCE.md)

---