4NK_node/docs/CONFIGURATION.md

# ⚙️ Guide de Configuration - 4NK Node

Guide complet pour configurer l'infrastructure 4NK Node selon vos besoins.

## 📋 Configuration Générale

### 1. Variables d'Environnement

Créer un fichier `.env` à la racine du projet :

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

### 2. Configuration Réseau

#### Réseau Docker Personnalisé

```bash
# Créer un réseau personnalisé
docker network create 4nk-network --subnet=172.20.0.0/16 --gateway=172.20.0.1

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

#### Configuration de Pare-feu

```bash
# Exposition publique centralisée via reverse proxy uniquement
sudo ufw allow 80/tcp     # HTTP (redirection)
sudo ufw allow 443/tcp    # HTTPS (UI + API + WS)
sudo ufw enable
sudo ufw enable

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

## 🔧 Configuration Bitcoin Core

### 1. Configuration de Base

Fichier : `bitcoin/bitcoin.conf`

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

# Configuration Signet
[signet]
listen=1
bind=0.0.0.0:38333
rpcbind=0.0.0.0:18443
rpcport=18443
fallbackfee=0.0001
blockfilterindex=1
datacarriersize=205
acceptnonstdtxn=1
dustrelayfee=0.00000001
minrelaytxfee=0.00000001
prune=0
signetchallenge=0020341c43803863c252df326e73574a27d7e19322992061017b0dc893e2eab90821
walletdir=/home/bitcoin/.bitcoin/wallets
wallet=mining
wallet=watchonly
maxtxfee=1
addnode=tlv2yqamflv22vfdzy2hha2nwmt6zrwrhjjzz4lx7qyq7lyc6wfhabyd.onion
```

### 2. Configuration Avancée

#### Performance

```ini
# Optimisation mémoire
dbcache=450
maxmempool=300
maxconnections=125

# Optimisation disque
txindex=1
blockfilterindex=1
coinstatsindex=1

# Optimisation réseau
listenonion=1
onion=tor:9050
proxy=tor:9050
```

#### Sécurité

```ini
# Authentification
rpcauth=bitcoin:c8ea921c7357bd6a5a8a7c43a12350a7$955e25b17672987b17c5a12f12cd8b9c1d38f0f86201c8cd47fc431f2e1c7956
rpcallowip=172.19.0.0/16
rpcworkqueue=32
rpcthreads=4
rpcdoccheck=1

# Limites
maxuploadtarget=5000
maxconnections=125
```

### 3. Configuration des Wallets

```bash
# Créer un wallet pour les relais
docker exec bitcoin-signet bitcoin-cli -signet createwallet "relay_wallet"

# Créer un wallet pour le mining
docker exec bitcoin-signet bitcoin-cli -signet createwallet "mining_wallet"

# Créer un wallet watch-only
docker exec bitcoin-signet bitcoin-cli -signet createwallet "watchonly_wallet" true
```

## 🔧 Configuration Blindbit

### 1. Configuration de Base

Fichier : `blindbit/blindbit.toml`

```toml
# Configuration Blindbit Oracle
host = "0.0.0.0:8000"
chain = "signet"
rpc_endpoint = "http://bitcoin:18443"
cookie_path = "/home/bitcoin/.bitcoin/signet/.cookie"
rpc_user = ""
rpc_pass = ""
sync_start_height = 1

# Performance
max_parallel_tweak_computations = 4
max_parallel_requests = 4

# Index
tweaks_only = 0
tweaks_full_basic = 1
tweaks_full_with_dust_filter = 1
tweaks_cut_through_with_dust_filter = 1
```

### 2. Configuration Avancée

#### Performance

```toml
# Optimisation des calculs
max_parallel_tweak_computations = 8
max_parallel_requests = 8

# Cache
cache_size = 1000
cache_ttl = 3600

# Logs
log_level = "info"
log_file = "/data/blindbit.log"
```

#### Sécurité

```toml
# Authentification
rpc_user = "blindbit_user"
rpc_pass = "secure_password"

# Limites
max_request_size = 1048576
rate_limit = 100
```

## 🔧 Configuration des Relais

### 1. Configuration de Base

#### Relay 1 - `sdk_relay/.conf.docker.relay1`

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

#### Relay 2 - `sdk_relay/.conf.docker.relay2`

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

#### Relay 3 - `sdk_relay/.conf.docker.relay3`

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

### 2. Configuration Avancée

#### Performance

```ini
# Optimisation mémoire
max_connections=100
connection_timeout=30
read_timeout=60

# Cache
cache_size=1000
cache_ttl=3600

# Logs
log_level=info
log_file=/home/bitcoin/.4nk/relay.log
```

#### Sécurité

```ini
# Authentification
auth_required=true
auth_token=your_secure_token

# Limites
max_message_size=1048576
rate_limit=1000
```

### 3. Configuration de Synchronisation

```ini
# Synchronisation
sync_enabled=true
sync_interval=30
sync_timeout=10

# Découverte
discovery_enabled=true
discovery_interval=60
discovery_timeout=5

# Cache de déduplication
dedup_enabled=true
dedup_ttl=300
dedup_max_size=10000
```

## 🌐 Configuration des Nœuds Externes

### 1. Configuration de Base

Fichier : `sdk_relay/external_nodes.conf`

```toml
# Configuration des nœuds externes
[relays]
external-relay-1 = "external-relay-1.example.com:8090"
external-relay-2 = "192.168.1.100:8090"
dev3-relay = "dev3.4nkweb.com:443"

[discovery]
auto_discover = true
bootstrap_nodes = [
    "bootstrap-1.4nk.net:8090",
    "bootstrap-2.4nk.net:8090"
]

[security]
allowed_domains = [
    "*.4nk.net",
    "*.example.com",
    "localhost",
    "127.0.0.1"
]

[validation]
max_connection_timeout = 10
health_check_interval = 300
blacklist_threshold = 5
```

### 2. Configuration Avancée

#### Découverte Automatique

```toml
[discovery]
auto_discover = true
bootstrap_nodes = [
    "bootstrap-1.4nk.net:8090",
    "bootstrap-2.4nk.net:8090"
]
discovery_interval = 300
discovery_timeout = 10
max_discovered_nodes = 50
```

#### Sécurité

```toml
[security]
allowed_domains = [
    "*.4nk.net",
    "*.example.com",
    "localhost",
    "127.0.0.1"
]
blocked_domains = [
    "malicious.example.com"
]
allowed_ips = [
    "192.168.1.0/24",
    "10.0.0.0/8"
]
```

#### Validation

```toml
[validation]
max_connection_timeout = 10
health_check_interval = 300
blacklist_threshold = 5
whitelist_enabled = false
certificate_verification = true
```

## 🔧 Configuration Tor

### 1. Image et service Tor

- Le service Tor est désormais construit localement depuis `tor/Dockerfile` et monté avec `tor/torrc`.
- Le conteneur tourne en utilisateur `debian-tor` et expose uniquement le SOCKS (9050) et, en interne, un ControlPort local (127.0.0.1:9051).

Extrait `docker-compose.yml` (service `tor`):

```yaml
services:
  tor:
    build: ./tor
    image: 4nk_node-tor
    container_name: tor-proxy
    ports:
      - "9050:9050"
      - "9051:9051"
    volumes:
      - ./tor/torrc:/etc/tor/torrc:ro
    command: ["tor", "-f", "/etc/tor/torrc"]
    healthcheck:
      test: ["CMD-SHELL", "nc -z 127.0.0.1 9050"]
      interval: 30s
      timeout: 5s
      retries: 3
    networks:
      - btcnet
```

### 2. Fichier `tor/torrc`

Configuration de base (extrait) :

```ini
SocksPort 0.0.0.0:9050
ControlPort 127.0.0.1:9051
DataDirectory /var/lib/tor
Log notice stdout
ClientUseIPv6 1
SafeLogging 1
ReducedConnectionPadding 1
SocksPolicy accept 0.0.0.0/0
AutomapHostsOnResolve 1
```

### 3. Bridges obfs4 (optionnels)

Pour contourner des filtrages réseaux, activer les bridges obfs4 dans `tor/torrc` :

```ini
UseBridges 1
ClientTransportPlugin obfs4 exec /usr/bin/obfs4proxy
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
```

L’image Tor installe `obfs4proxy`. Après modification :

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

Vérifications :

```bash
sudo docker compose ps tor
sudo docker logs tor-proxy --tail=40
sudo docker exec tor-proxy nc -z 127.0.0.1 9050 && echo SOCKS:OK
```

#### Notes et recommandations (Tor/bridges)

- Le `ControlPort 127.0.0.1:9051` est utilisé pour le diagnostic interne. Ne pas l’exposer publiquement. Une authentification peut être activée si un contrôle à distance est requis.
- Les bridges obfs4 ci‑dessus proviennent de la page de référence du Tor Project. En cas d’échec répété (messages « general SOCKS server failure » côté Tor), ajouter 2–3 bridges supplémentaires depuis la même source et redémarrer le service Tor.
- Pour faciliter l’ajout à chaud de bridges, un fichier `tor/bridges.extra` est monté en lecture seule dans le conteneur et inclus via `%include /etc/tor/bridges.extra`. Vous pouvez y coller de nouveaux bridges sans modifier `tor/torrc`, puis redémarrer Tor.
- Les tests de connectivité doivent distinguer :
  - Accès SOCKS vers des services onion « publics » (ex. DuckDuckGo) pour valider le proxy Tor.
  - Accès SOCKS vers l’onion cible du signet pour valider la reachability du pair.
- À la date d’édition, le proxy SOCKS fonctionne (onion publics accessibles), mais le pair signet `.onion:38333` est injoignable (host unreachable). La configuration du signet (signetchallenge et addnode) doit rester inchangée, conformément à la contrainte fonctionnelle.

#### Outils de diagnostic réseau

- Installer `netcat-openbsd` sur l’hôte et dans les conteneurs pertinents pour faciliter les vérifications :
  - Hôte : `sudo apt-get install -y netcat-openbsd`
  - Conteneur Bitcoin (root) : `apt-get update && apt-get install -y --no-install-recommends netcat-openbsd`
- Exemples de vérifications :
  - `nc -vz -w 10 -x 127.0.0.1:9050 -X 5 <onion> 80`
  - `nc -vz -w 10 -x 127.0.0.1:9050 -X 5 <onion_signet> 38333`

#### DNS externes (ex. dev.4nkweb.com)

- Si un nom de domaine (ex. `dev.4nkweb.com`) doit pointer vers un service, s’assurer qu’un enregistrement DNS A/AAAA existe. En l’absence de résolution, les tests échoueront côté HTTP/HTTPS et TCP.
- En phase de test, une entrée temporaire peut être ajoutée dans `/etc/hosts` si l’IP est connue.

## 🔧 Configuration Docker Compose

### 1. Configuration de Base

Fichier : `docker-compose.yml`

```yaml
# Compose modernisé (sans clé version), publication unique via reverse proxy
services:
  reverse_proxy:
    image: nginx:alpine
    depends_on:
      - sdk_relay_1
    volumes:
      - ./proxy/nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./certs:/etc/nginx/certs:ro
      - ./ihm_client/dist:/usr/share/nginx/html:ro
    ports:
      - "80:80"
      - "443:443"
    networks:
      btcnet:
        aliases:
          - reverse_proxy

  # Tous les autres services sont internes (pas de ports exposés)
  bitcoin:
    networks:
      - btcnet
  blindbit:
    networks:
      - btcnet
  sdk_relay_1:
    networks:
      - btcnet
```

### 2. Configuration Avancée

#### Ressources

```yaml
services:
  bitcoin:
    deploy:
      resources:
        limits:
          memory: 2G
          cpus: '1.0'
        reservations:
          memory: 1G
          cpus: '0.5'

  sdk_relay_1:
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: '0.5'
        reservations:
          memory: 256M
          cpus: '0.25'
```

#### Sécurité

```yaml
services:
  bitcoin:
    security_opt:
      - no-new-privileges:true
    read_only: false
    tmpfs:
      - /tmp:noexec,nosuid,size=100m

  sdk_relay_1:
    security_opt:
      - no-new-privileges:true
    read_only: false
    tmpfs:
      - /tmp:noexec,nosuid,size=50m
```

## 🔧 Configuration SSL/TLS

### 1. Certificat Auto-Signé

```bash
# Générer et protéger des certificats auto-signés
./scripts/generate_certs.sh

# Les certificats sont montés par le reverse proxy :
#   - certs/server.crt -> /etc/nginx/certs/server.crt
#   - certs/server.key -> /etc/nginx/certs/server.key
```

### 2. Certificat Let's Encrypt

```bash
# Installer certbot
sudo apt install certbot python3-certbot-nginx

# Obtenir un certificat
sudo certbot --nginx -d your-domain.com

# Configuration automatique
sudo certbot renew --dry-run
```

## 🔧 Configuration de Monitoring

### 1. Prometheus

```yaml
# docker-compose.yml addition
services:
  prometheus:
    image: prom/prometheus:latest
    container_name: prometheus
    ports:
      - "9090:9090"
    volumes:
      - ./prometheus.yml:/etc/prometheus/prometheus.yml
      - prometheus_data:/prometheus
    command:
      - '--config.file=/etc/prometheus/prometheus.yml'
      - '--storage.tsdb.path=/prometheus'
      - '--web.console.libraries=/etc/prometheus/console_libraries'
      - '--web.console.templates=/etc/prometheus/consoles'
      - '--storage.tsdb.retention.time=200h'
      - '--web.enable-lifecycle'

  grafana:
    image: grafana/grafana:latest
    container_name: grafana
    ports:
      - "3000:3000"
    volumes:
      - grafana_data:/var/lib/grafana
    environment:
      - GF_SECURITY_ADMIN_PASSWORD=admin

volumes:
  prometheus_data:
  grafana_data:
```

### 2. Configuration Prometheus

Fichier : `prometheus.yml`

```yaml
global:
  scrape_interval: 15s
  evaluation_interval: 15s

rule_files:
  # - "first_rules.yml"
  # - "second_rules.yml"

scrape_configs:
  - job_name: 'bitcoin'
    static_configs:
      - targets: ['bitcoin:18443']

  - job_name: 'blindbit'
    static_configs:
      - targets: ['blindbit:8000']

  - job_name: 'sdk_relay'
    static_configs:
      - targets: ['sdk_relay_1:8091']
```

## 🔧 Configuration de Sauvegarde

### 1. Script de Sauvegarde

```bash
#!/bin/bash
# backup_4nk.sh

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/
cp bitcoin/bitcoin.conf $BACKUP_DIR/
cp blindbit/blindbit.toml $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/

# Sauvegarder les données Blindbit
docker exec blindbit-oracle tar czf /tmp/blindbit-backup.tar.gz /data
docker cp blindbit-oracle:/tmp/blindbit-backup.tar.gz $BACKUP_DIR/

# Sauvegarder les données des relais
for i in {1..3}; do
    docker exec sdk_relay_$i tar czf /tmp/relay_$i-backup.tar.gz /home/bitcoin/.4nk
    docker cp sdk_relay_$i:/tmp/relay_$i-backup.tar.gz $BACKUP_DIR/
done

# Nettoyer les anciennes sauvegardes (garder 7 jours)
find /backup -name "4nk_node_*" -type d -mtime +7 -exec rm -rf {} \;

echo "Sauvegarde terminée: $BACKUP_DIR"
```

### 2. Configuration Cron

```bash
# Ajouter au cron pour sauvegarde automatique
echo "0 2 * * * /path/to/backup_4nk.sh" | crontab -
```

## 🔧 Configuration de Logs

### 1. Rotation des Logs

```bash
# Configuration logrotate
cat > /etc/logrotate.d/4nk-node << EOF
/var/lib/docker/containers/*/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
    size 100M
}
EOF
```

### 2. Centralisation des Logs

```yaml
# docker-compose.yml addition
services:
  elasticsearch:
    image: docker.elastic.co/elasticsearch/elasticsearch:7.17.0
    container_name: elasticsearch
    environment:
      - discovery.type=single-node
    ports:
      - "9200:9200"
    volumes:
      - elasticsearch_data:/usr/share/elasticsearch/data

  kibana:
    image: docker.elastic.co/kibana/kibana:7.17.0
    container_name: kibana
    ports:
      - "5601:5601"
    depends_on:
      - elasticsearch

  filebeat:
    image: docker.elastic.co/beats/filebeat:7.17.0
    container_name: filebeat
    volumes:
      - /var/lib/docker/containers:/var/lib/docker/containers:ro
      - ./filebeat.yml:/usr/share/filebeat/filebeat.yml:ro
    depends_on:
      - elasticsearch

volumes:
  elasticsearch_data:
```

## 📝 Checklist de Configuration

- [ ] Variables d'environnement configurées
- [ ] Configuration Bitcoin Core vérifiée
- [ ] Configuration Blindbit vérifiée
- [ ] Configurations des relais vérifiées
- [ ] Configuration des nœuds externes vérifiée
- [ ] Configuration Tor vérifiée
- [ ] Configuration Docker Compose vérifiée
- [ ] SSL/TLS configuré (si nécessaire)
- [ ] Monitoring configuré (si nécessaire)
- [ ] Sauvegarde configurée
- [ ] Logs configurés
- [ ] Pare-feu configuré
- [ ] Tests de configuration passés

## 🎯 Commandes de Configuration

```bash
# Vérifier la configuration
docker-compose config

# Tester la configuration
./test_final_sync.sh

# Appliquer la configuration
./restart_4nk_node.sh

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

---