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.

⚡ Installation Rapide (Recommandée)

Pour une installation rapide et automatisée, utilisez le script bootstrap :

# Cloner le repository
git clone https://git.4nkweb.com/4nk/4NK_IA_back.git
cd 4NK_IA_back

# Bootstrap automatique
chmod +x ops/bootstrap.sh
./ops/bootstrap.sh

Le script bootstrap configure automatiquement :

• ✅ Vérification des prérequis
• ✅ Configuration de l'environnement
• ✅ Téléchargement des images Docker
• ✅ Démarrage des services
• ✅ Configuration des modèles Ollama
• ✅ Setup des workspaces AnythingLLM
• ✅ Vérifications finales

Services disponibles après installation :

• 🌐 API Notariale : http://localhost:8000
• 📚 Documentation API : http://localhost:8000/docs
• 🤖 AnythingLLM : http://localhost:3001
• 📊 Grafana : http://localhost:3000
• 🗄️ MinIO Console : http://localhost:9001
• 🦙 Ollama : http://localhost:11434

⚠️ Configuration MinIO

Important : Le fichier .env est créé automatiquement avec les bonnes configurations. Si vous rencontrez des erreurs MinIO, vérifiez que MINIO_ENDPOINT ne contient pas de protocole (ex: minio:9000 et non http://minio:9000).

📋 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

# 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

# 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

# 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

# Installation via Homebrew
brew install --cask docker

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

Windows (WSL2)

# 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

# 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

# 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

# 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

# Installation via Homebrew
brew install python@3.13

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

5. Installation de Git

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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

2. Démarrage Manuel

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

# Démarrage de l'interface web
cd services/web_interface
python3 start_web.py 8081 &

3. Vérification du Démarrage

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

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

🧪 Tests d'Installation

1. Tests Automatiques

# Exécution des tests
pytest tests/ -v

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

2. Tests Manuels

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

# Test de l'interface web
# Ouvrir http://localhost:8081 dans un navigateur

3. Tests de Performance

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

# 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

# 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

# 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

# Correction des permissions
sudo chown -R $USER:$USER .
chmod -R 755 .

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

Logs et Diagnostic

# 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	-
Web UI	http://localhost:8081	-
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

# 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

# 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

# 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

# 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

🔧 Dépannage

Problèmes Courants

Erreur MinIO "path in endpoint is not allowed"

# Symptôme : L'API redémarre constamment avec cette erreur
# Solution : Vérifier la configuration MINIO_ENDPOINT
grep MINIO_ENDPOINT infra/.env
# Doit afficher : MINIO_ENDPOINT=minio:9000 (sans http://)

Services non accessibles

# Vérifier le statut des conteneurs
docker compose ps

# Vérifier les logs
docker compose logs host-api

# Redémarrer un service
docker compose restart host-api

Ports déjà utilisés

# Vérifier les ports utilisés
netstat -tulpn | grep :8000

# Changer les ports dans docker-compose.yml si nécessaire

Commandes de Diagnostic

# Test de l'API
curl http://localhost:8000/api/health

# Test de MinIO
curl http://localhost:9001

# Vérification des volumes
docker volume ls | grep infra

# Nettoyage complet
docker compose down -v
docker system prune -f

🆘 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 git.4nkweb.com : 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