4NK_IA_back/docs/INSTALLATION.md

# Guide d'Installation - Système Notarial 4NK_IA

## 🚀 Vue d'ensemble

Ce guide vous accompagne dans l'installation complète du système notarial 4NK_IA, de l'environnement de développement à la production.

## 📋 Prérequis

### **Système d'Exploitation**

| OS | Version | Support |
|----|---------|---------|
| **Ubuntu** | 20.04 LTS+ | ✅ Recommandé |
| **Debian** | 11+ | ✅ Supporté |
| **CentOS** | 8+ | ✅ Supporté |
| **RHEL** | 8+ | ✅ Supporté |
| **Windows** | 10+ (WSL2) | ✅ Supporté |
| **macOS** | 12+ | ✅ Supporté |

### **Ressources Système**

#### **Minimum**
- **CPU** : 4 cœurs
- **RAM** : 8 GB
- **Stockage** : 50 GB SSD
- **Réseau** : 100 Mbps

#### **Recommandé**
- **CPU** : 8 cœurs
- **RAM** : 16 GB
- **Stockage** : 100 GB SSD
- **Réseau** : 1 Gbps

#### **Production**
- **CPU** : 16 cœurs
- **RAM** : 32 GB
- **Stockage** : 500 GB SSD
- **Réseau** : 10 Gbps

## 🔧 Installation des Prérequis

### **1. Mise à jour du Système**

```bash
# Ubuntu/Debian
sudo apt update && sudo apt upgrade -y

# CentOS/RHEL
sudo yum update -y

# macOS
brew update && brew upgrade
```

### **2. Installation de Docker**

#### **Ubuntu/Debian**
```bash
# Suppression des anciennes versions
sudo apt remove docker docker-engine docker.io containerd runc

# Installation des dépendances
sudo apt install -y \
    ca-certificates \
    curl \
    gnupg \
    lsb-release

# Ajout de la clé GPG officielle
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

# Ajout du dépôt
echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \
  $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

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

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

# Redémarrage de la session
newgrp docker
```

#### **CentOS/RHEL**
```bash
# Installation des dépendances
sudo yum install -y yum-utils

# Ajout du dépôt Docker
sudo yum-config-manager --add-repo https://download.docker.com/linux/centos/docker-ce.repo

# Installation de Docker
sudo yum install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Démarrage et activation
sudo systemctl start docker
sudo systemctl enable docker

# Ajout de l'utilisateur au groupe docker
sudo usermod -aG docker $USER
```

#### **macOS**
```bash
# Installation via Homebrew
brew install --cask docker

# Ou téléchargement depuis le site officiel
# https://www.docker.com/products/docker-desktop
```

#### **Windows (WSL2)**
```powershell
# Installation de Docker Desktop
# Télécharger depuis : https://www.docker.com/products/docker-desktop

# Activation de WSL2 dans Docker Desktop
# Settings > General > Use the WSL 2 based engine
```

### **3. Installation de Docker Compose**

```bash
# Vérification de l'installation
docker --version
docker compose version

# Si Docker Compose n'est pas installé
sudo curl -L "https://github.com/docker/compose/releases/latest/download/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
sudo chmod +x /usr/local/bin/docker-compose
```

### **4. Installation de Python 3.13**

#### **Ubuntu/Debian**
```bash
# Ajout du dépôt deadsnakes
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update

# Installation de Python 3.13
sudo apt install -y python3.13 python3.13-venv python3.13-dev python3-pip

# Vérification
python3.13 --version
pip3 --version
```

#### **CentOS/RHEL**
```bash
# Installation d'EPEL
sudo yum install -y epel-release

# Installation de Python 3.13
sudo yum install -y python313 python313-pip python313-devel

# Vérification
python3.13 --version
pip3 --version
```

#### **macOS**
```bash
# Installation via Homebrew
brew install python@3.13

# Vérification
python3.13 --version
pip3 --version
```

### **5. Installation de Git**

```bash
# Ubuntu/Debian
sudo apt install -y git

# CentOS/RHEL
sudo yum install -y git

# macOS
brew install git

# Configuration
git config --global user.name "Votre Nom"
git config --global user.email "votre.email@example.com"
```

## 📥 Installation du Projet

### **1. Clonage du Dépôt**

```bash
# Clonage du dépôt
git clone https://git.4nkweb.com/4nk/4NK_IA.git
cd 4NK_IA

# Vérification de la branche
git branch -a
git checkout dev
```

### **2. Configuration de l'Environnement**

```bash
# Copie du fichier de configuration
cp infra/.env.example infra/.env

# Édition de la configuration
nano infra/.env
```

### **3. Création de l'Environnement Python**

```bash
# Création de l'environnement virtuel
python3.13 -m venv venv

# Activation de l'environnement
source venv/bin/activate

# Mise à jour de pip
pip install --upgrade pip

# Installation des dépendances
pip install -r requirements-test.txt
```

### **4. Installation des Dépendances Système**

#### **Ubuntu/Debian**
```bash
# Dépendances pour l'OCR
sudo apt install -y \
    tesseract-ocr \
    tesseract-ocr-fra \
    libtesseract-dev \
    poppler-utils \
    libpoppler-cpp-dev

# Dépendances pour l'image processing
sudo apt install -y \
    libopencv-dev \
    python3-opencv \
    libgl1-mesa-glx \
    libglib2.0-0

# Dépendances pour PostgreSQL
sudo apt install -y \
    postgresql-client \
    libpq-dev

# Dépendances pour Redis
sudo apt install -y \
    redis-tools
```

#### **CentOS/RHEL**
```bash
# Dépendances pour l'OCR
sudo yum install -y \
    tesseract \
    tesseract-langpack-fra \
    poppler-utils

# Dépendances pour l'image processing
sudo yum install -y \
    opencv-devel \
    mesa-libGL \
    glib2

# Dépendances pour PostgreSQL
sudo yum install -y \
    postgresql \
    postgresql-devel

# Dépendances pour Redis
sudo yum install -y \
    redis
```

## 🐳 Installation avec Docker

### **1. Installation Complète**

```bash
# Construction des images
docker compose -f infra/docker-compose.yml build

# Démarrage des services
docker compose -f infra/docker-compose.yml up -d

# Vérification du statut
docker compose -f infra/docker-compose.yml ps
```

### **2. Installation de Développement**

```bash
# Démarrage des services de base
docker compose -f infra/docker-compose.dev.yml up -d

# Vérification
docker compose -f infra/docker-compose.dev.yml ps
```

### **3. Installation des Modèles LLM**

```bash
# Téléchargement des modèles Ollama
docker exec -it 4nk_ia-ollama-1 ollama pull llama3:8b
docker exec -it 4nk_ia-ollama-1 ollama pull mistral:7b

# Vérification des modèles
docker exec -it 4nk_ia-ollama-1 ollama list
```

## 🔧 Configuration Post-Installation

### **1. Configuration de la Base de Données**

```bash
# Connexion à PostgreSQL
docker exec -it 4nk_ia-postgres-1 psql -U notariat -d notariat

# Création des tables
\i /docker-entrypoint-initdb.d/init.sql

# Vérification
\dt
```

### **2. Configuration de MinIO**

```bash
# Accès à la console MinIO
# URL: http://localhost:9001
# Utilisateur: minio
# Mot de passe: minio_pwd

# Création du bucket
docker exec -it 4nk_ia-minio-1 mc mb minio/ingest
```

### **3. Configuration de Neo4j**

```bash
# Accès au navigateur Neo4j
# URL: http://localhost:7474
# Utilisateur: neo4j
# Mot de passe: neo4j_pwd

# Création des contraintes
docker exec -it 4nk_ia-neo4j-1 cypher-shell -u neo4j -p neo4j_pwd
```

### **4. Configuration d'OpenSearch**

```bash
# Vérification de l'état
curl -X GET "localhost:9200/_cluster/health?pretty"

# Création des index
curl -X PUT "localhost:9200/documents" -H 'Content-Type: application/json' -d'
{
  "mappings": {
    "properties": {
      "title": {"type": "text"},
      "content": {"type": "text"},
      "created_at": {"type": "date"}
    }
  }
}'
```

## 🚀 Démarrage du Système

### **1. Démarrage Automatique**

```bash
# Utilisation du script de démarrage
chmod +x start_notary_system.sh
./start_notary_system.sh
```

### **2. Démarrage Manuel**

```bash
# Démarrage des services Docker
docker compose -f infra/docker-compose.yml up -d

# Démarrage de l'API
cd services/host_api
source ../../venv/bin/activate
python3 app_complete.py &

# Démarrage du worker
cd services/worker
source ../../venv/bin/activate
celery -A worker worker --loglevel=info &

# (IHM supprimée) — Backend uniquement
```

### **3. Vérification du Démarrage**

```bash
# Vérification des services
curl -f http://localhost:8000/api/health

# Vérification des logs
docker compose -f infra/docker-compose.yml logs -f
```

## 🧪 Tests d'Installation

### **1. Tests Automatiques**

```bash
# Exécution des tests
pytest tests/ -v

# Tests avec couverture
pytest tests/ --cov=services --cov-report=html
```

### **2. Tests Manuels**

```bash
# Test de l'API
curl -X POST http://localhost:8000/api/notary/upload \
  -F "file=@test_document.pdf" \
  -F "id_dossier=test_001" \
  -F "etude_id=etude_001" \
  -F "utilisateur_id=user_001"

# (IHM supprimée) — pas de test d’interface web
```

### **3. Tests de Performance**

```bash
# Test de charge avec Apache Bench
ab -n 100 -c 10 http://localhost:8000/api/health

# Test de charge avec wrk
wrk -t12 -c400 -d30s http://localhost:8000/api/health
```

## 🔍 Dépannage

### **Problèmes Courants**

#### **1. Port déjà utilisé**
```bash
# Vérification des ports
netstat -tulpn | grep :8000
lsof -i :8000

# Arrêt des processus
sudo kill -9 $(lsof -t -i:8000)
```

#### **2. Erreur de connexion à la base de données**
```bash
# Vérification de PostgreSQL
docker exec -it 4nk_ia-postgres-1 pg_isready -U notariat

# Vérification des logs
docker logs 4nk_ia-postgres-1
```

#### **3. Erreur de mémoire**
```bash
# Vérification de la mémoire
free -h
docker stats

# Augmentation de la mémoire Docker
# Docker Desktop > Settings > Resources > Memory
```

#### **4. Erreur de permissions**
```bash
# Correction des permissions
sudo chown -R $USER:$USER .
chmod -R 755 .

# Permissions Docker
sudo usermod -aG docker $USER
newgrp docker
```

### **Logs et Diagnostic**

```bash
# Logs des services
docker compose -f infra/docker-compose.yml logs -f api
docker compose -f infra/docker-compose.yml logs -f worker
docker compose -f infra/docker-compose.yml logs -f postgres

# Logs système
journalctl -u docker -f
tail -f /var/log/syslog
```

## 📊 Monitoring Post-Installation

### **1. Accès aux Interfaces**

| Service | URL | Identifiants |
|---------|-----|--------------|
| **API** | http://localhost:8000 | - |
| **Grafana** | http://localhost:3000 | admin/admin |
| **MinIO** | http://localhost:9001 | minio/minio_pwd |
| **Neo4j** | http://localhost:7474 | neo4j/neo4j_pwd |
| **Prometheus** | http://localhost:9090 | - |

### **2. Métriques à Surveiller**

```bash
# Vérification des métriques
curl http://localhost:9090/metrics
curl http://localhost:8000/metrics
```

### **3. Alertes Configurées**

- **CPU** > 80% pendant 5 minutes
- **Mémoire** > 90% pendant 2 minutes
- **Disque** > 85% d'utilisation
- **Erreurs API** > 5% pendant 1 minute
- **Temps de réponse** > 5 secondes

## 🔄 Mise à Jour

### **1. Mise à jour du Code**

```bash
# Récupération des dernières modifications
git pull origin dev

# Reconstruction des images
docker compose -f infra/docker-compose.yml build

# Redémarrage des services
docker compose -f infra/docker-compose.yml up -d
```

### **2. Mise à jour des Dépendances**

```bash
# Mise à jour des packages Python
pip install --upgrade -r requirements-test.txt

# Mise à jour des images Docker
docker compose -f infra/docker-compose.yml pull
docker compose -f infra/docker-compose.yml up -d
```

### **3. Sauvegarde Avant Mise à Jour**

```bash
# Sauvegarde de la base de données
docker exec 4nk_ia-postgres-1 pg_dump -U notariat notariat > backup_$(date +%Y%m%d_%H%M%S).sql

# Sauvegarde des volumes
docker run --rm -v 4nk_ia_pgdata:/data -v $(pwd):/backup alpine tar czf /backup/pgdata_backup.tar.gz -C /data .
```

## 📋 Checklist d'Installation

### **Pré-installation**
- [ ] **Système d'exploitation** compatible
- [ ] **Ressources système** suffisantes
- [ ] **Accès réseau** configuré
- [ ] **Utilisateur** avec privilèges sudo

### **Installation des Prérequis**
- [ ] **Docker** installé et configuré
- [ ] **Docker Compose** installé
- [ ] **Python 3.13** installé
- [ ] **Git** installé et configuré
- [ ] **Dépendances système** installées

### **Installation du Projet**
- [ ] **Dépôt cloné** depuis Git
- [ ] **Configuration** copiée et éditée
- [ ] **Environnement Python** créé
- [ ] **Dépendances Python** installées

### **Configuration des Services**
- [ ] **Base de données** configurée
- [ ] **MinIO** configuré
- [ ] **Neo4j** configuré
- [ ] **OpenSearch** configuré
- [ ] **Modèles LLM** téléchargés

### **Tests et Validation**
- [ ] **Services** démarrés correctement
- [ ] **API** répond aux requêtes
- [ ] **Interface web** accessible
- [ ] **Tests automatiques** passent
- [ ] **Monitoring** opérationnel

### **Sécurité**
- [ ] **Firewall** configuré
- [ ] **Certificats SSL** installés
- [ ] **Mots de passe** changés
- [ ] **Accès** restreint
- [ ] **Sauvegardes** configurées

## 🆘 Support

### **Documentation**
- **README.md** : Vue d'ensemble du projet
- **ARCHITECTURE.md** : Architecture détaillée
- **CONFIGURATION.md** : Configuration complète
- **NETWORK.md** : Architecture réseau

### **Communauté**
- **Issues GitHub** : Signalement de bugs
- **Discussions** : Questions et suggestions
- **Wiki** : Documentation communautaire

### **Support Commercial**
- **Email** : support@4nkweb.com
- **Téléphone** : +33 1 23 45 67 89
- **Chat** : Disponible 24/7