rpa_vision_v3/docs/guides/BUILD_DEPLOY_GUIDE.md

# Guide Build & Déploiement - Agent V0 + Serveur

**Date:** 24 novembre 2025

## 📋 Vue d'Ensemble

Ce guide explique comment:
1. **Builder les exécutables** Windows/macOS/Linux
2. **Déployer le serveur API** pour recevoir les uploads
3. **Tester end-to-end** agent → serveur

---

## 🔨 Part 1: Build des Exécutables

### Prérequis

**Tous OS:**
- Python 3.10+
- pip
- Git (pour cloner le projet)

**Windows:**
- Visual Studio Build Tools (pour cryptography)
- Ou: Installer via `pip install cryptography` (binaires pré-compilés)

**macOS:**
- Xcode Command Line Tools: `xcode-select --install`

**Linux:**
- `sudo apt-get install python3-dev libssl-dev`

### 1.1 Build Windows (.exe)

**Sur une machine Windows:**

```cmd
cd agent_v0

REM Méthode 1: Script automatique
build_windows.bat

REM Méthode 2: Manuel
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
pip install pyinstaller pywin32
pyinstaller agent_v0.spec --clean --noconfirm
```

**Résultat:**
```
dist/agent_v0.exe  (~50-80 MB)
```

**Test:**
```cmd
dist\agent_v0.exe
```

### 1.2 Build macOS (.app)

**Sur une machine macOS:**

```bash
cd agent_v0

# Méthode 1: Script automatique
./build_macos.sh

# Méthode 2: Manuel
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install pyinstaller pyobjc-framework-Cocoa
pyinstaller agent_v0.spec --clean --noconfirm
```

**Résultat:**
```
dist/agent_v0.app/  (~60-90 MB)
```

**Test:**
```bash
open dist/agent_v0.app
```

**⚠️ Permissions macOS:**

Première exécution → macOS demandera les permissions:
1. System Preferences > Security & Privacy > Privacy
2. Accessibility → Cocher `agent_v0`
3. Screen Recording → Cocher `agent_v0`

### 1.3 Build Linux (binaire)

**Sur une machine Linux:**

```bash
cd agent_v0

# Méthode 1: Script automatique
./build_linux.sh

# Méthode 2: Manuel
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
pip install pyinstaller
pyinstaller agent_v0.spec --clean --noconfirm
```

**Résultat:**
```
dist/agent_v0  (~60-90 MB)
```

**Test:**
```bash
./dist/agent_v0
```

**⚠️ Dépendances Linux:**
```bash
sudo apt-get install xdotool  # Pour détection fenêtre active
```

---

## 🚀 Part 2: Déploiement Serveur

### 2.1 Installation Serveur

**Sur le serveur Linux (où tourne RPA Vision V3):**

```bash
cd /path/to/rpa_vision_v3

# Installer dépendances serveur
pip install -r server/requirements_server.txt

# Ou manuellement:
pip install fastapi uvicorn[standard] python-multipart cryptography
```

### 2.2 Configuration

**Définir le password de chiffrement:**

```bash
# Option 1: Variable d'environnement
export ENCRYPTION_PASSWORD="VotreCléSecrète2025"

# Option 2: Fichier .env
echo 'ENCRYPTION_PASSWORD="VotreCléSecrète2025"' > server/.env

# Option 3: Hardcoder dans api_upload.py (pas recommandé)
# ENCRYPTION_PASSWORD = "VotreCléSecrète2025"
```

**⚠️ Important:** Utiliser le **même password** que dans `agent_config.json` des agents!

### 2.3 Démarrage Serveur

**Méthode 1: Script automatique**
```bash
cd server
./start_server.sh
```

**Méthode 2: Uvicorn direct**
```bash
cd server
uvicorn api_upload:app --host 0.0.0.0 --port 8000
```

**Méthode 3: Production avec systemd**

Créer `/etc/systemd/system/rpa-api.service`:
```ini
[Unit]
Description=RPA Vision V3 - API Upload
After=network.target

[Service]
Type=simple
User=rpa
WorkingDirectory=/path/to/rpa_vision_v3/server
Environment="ENCRYPTION_PASSWORD=VotreCléSecrète2025"
ExecStart=/path/to/venv/bin/uvicorn api_upload:app --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target
```

Activer:
```bash
sudo systemctl daemon-reload
sudo systemctl enable rpa-api
sudo systemctl start rpa-api
sudo systemctl status rpa-api
```

### 2.4 Vérification Serveur

**Test status:**
```bash
curl http://localhost:8000/api/traces/status
```

**Réponse attendue:**
```json
{
  "status": "online",
  "version": "1.0.0",
  "upload_dir": "data/training/uploads",
  "sessions_dir": "data/training/sessions",
  "encryption_enabled": true
}
```

---

## 🔗 Part 3: Configuration Agent → Serveur

### 3.1 Configurer URL Serveur

**Sur chaque agent (Windows/macOS/Linux):**

Éditer `agent_config.json`:
```json
{
  "enable_encryption": true,
  "encryption_password": "VotreCléSecrète2025",
  "server_url": "https://votre-serveur.com/api/traces/upload"
}
```

**⚠️ Important:**
- Utiliser **HTTPS** en production (pas HTTP)
- Même `encryption_password` que le serveur
- URL complète avec `/api/traces/upload`

### 3.2 Mettre à Jour config.py

**Dans `agent_v0/config.py`:**

```python
# Avant (placeholder)
SERVER_URL = "https://example.com/api/traces/upload"

# Après (production)
SERVER_URL = "https://votre-serveur.com/api/traces/upload"
```

**Ou:** Lire depuis `agent_config.json` (recommandé):

```python
# config.py
import json
from pathlib import Path

config_file = Path(__file__).parent / "agent_config.json"
if config_file.exists():
    with open(config_file) as f:
        config = json.load(f)
    SERVER_URL = config.get("server_url", "https://example.com/api/traces/upload")
else:
    SERVER_URL = "https://example.com/api/traces/upload"
```

---

## 🧪 Part 4: Test End-to-End

### 4.1 Test Local (même machine)

**Terminal 1: Démarrer serveur**
```bash
cd server
./start_server.sh
```

**Terminal 2: Tester agent**
```bash
cd agent_v0

# Configurer pour local
echo '{
  "user_id": "test_user",
  "enable_encryption": true,
  "encryption_password": "test_password_123",
  "server_url": "http://localhost:8000/api/traces/upload"
}' > agent_config.json

# Lancer agent
python main.py

# Ou exécutable:
./dist/agent_v0  # Linux
open dist/agent_v0.app  # macOS
dist\agent_v0.exe  # Windows
```

**Actions:**
1. Clic gauche sur icône tray → Start session
2. Faire quelques clics dans des applications
3. Clic gauche sur icône tray → Stop session
4. Vérifier upload dans logs

**Terminal 3: Vérifier réception**
```bash
curl http://localhost:8000/api/traces/sessions
```

### 4.2 Test Production (réseau)

**Serveur:**
```bash
# Démarrer sur IP publique
cd server
export ENCRYPTION_PASSWORD="VotreCléSecrète2025"
uvicorn api_upload:app --host 0.0.0.0 --port 8000
```

**Agent (machine distante):**
```json
{
  "encryption_password": "VotreCléSecrète2025",
  "server_url": "https://votre-serveur.com/api/traces/upload"
}
```

**Test upload manuel:**
```bash
# Créer une session test
cd agent_v0
python main.py
# Start → quelques clics → Stop

# Vérifier fichier créé
ls -lh sessions/*.enc

# Upload manuel avec curl
curl -X POST \
  -F "file=@sessions/sess_xxx.enc" \
  -F "session_id=sess_xxx" \
  https://votre-serveur.com/api/traces/upload
```

---

## 📦 Part 5: Distribution aux Formateurs

### 5.1 Package Windows

**Créer installeur NSIS (optionnel):**

```nsis
; installer.nsi
!include "MUI2.nsh"

Name "Agent V0"
OutFile "agent_v0_installer.exe"
InstallDir "$PROGRAMFILES\AgentV0"

!insertmacro MUI_PAGE_DIRECTORY
!insertmacro MUI_PAGE_INSTFILES
!insertmacro MUI_LANGUAGE "French"

Section "Install"
  SetOutPath "$INSTDIR"
  File "dist\agent_v0.exe"
  File "agent_config.json"
  
  CreateShortcut "$DESKTOP\Agent V0.lnk" "$INSTDIR\agent_v0.exe"
  CreateShortcut "$SMPROGRAMS\Agent V0.lnk" "$INSTDIR\agent_v0.exe"
SectionEnd
```

Compiler:
```cmd
makensis installer.nsi
```

### 5.2 Package macOS

**Créer DMG:**
```bash
# Installer create-dmg
brew install create-dmg

# Créer DMG
create-dmg \
  --volname "Agent V0" \
  --window-pos 200 120 \
  --window-size 600 400 \
  --icon-size 100 \
  --icon "agent_v0.app" 175 120 \
  --app-drop-link 425 120 \
  "agent_v0_installer.dmg" \
  "dist/agent_v0.app"
```

### 5.3 Package Linux

**Créer .deb:**
```bash
# Structure
mkdir -p agent_v0_deb/DEBIAN
mkdir -p agent_v0_deb/usr/local/bin
mkdir -p agent_v0_deb/usr/share/applications

# Control file
cat > agent_v0_deb/DEBIAN/control << EOF
Package: agent-v0
Version: 0.1.0
Architecture: amd64
Maintainer: RPA Vision <contact@rpavision.com>
Description: Agent d'enregistrement pour RPA Vision V3
Depends: xdotool
EOF

# Copier binaire
cp dist/agent_v0 agent_v0_deb/usr/local/bin/

# Desktop entry
cat > agent_v0_deb/usr/share/applications/agent_v0.desktop << EOF
[Desktop Entry]
Name=Agent V0
Exec=/usr/local/bin/agent_v0
Type=Application
Categories=Utility;
EOF

# Build
dpkg-deb --build agent_v0_deb
mv agent_v0_deb.deb agent_v0_0.1.0_amd64.deb
```

---

## 🔒 Part 6: Sécurité Production

### 6.1 HTTPS (Obligatoire)

**Avec Nginx + Let's Encrypt:**

```nginx
# /etc/nginx/sites-available/rpa-api
server {
    listen 443 ssl http2;
    server_name votre-serveur.com;
    
    ssl_certificate /etc/letsencrypt/live/votre-serveur.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/votre-serveur.com/privkey.pem;
    
    location /api/traces/ {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        client_max_body_size 100M;  # Pour gros uploads
    }
}
```

### 6.2 Firewall

```bash
# Autoriser seulement HTTPS
sudo ufw allow 443/tcp
sudo ufw deny 8000/tcp  # Bloquer accès direct à uvicorn
```

### 6.3 Authentification (Optionnel)

**Ajouter API key:**

```python
# api_upload.py
from fastapi import Header, HTTPException

API_KEY = os.getenv("API_KEY", "changeme")

@app.post("/api/traces/upload")
async def upload_session(
    file: UploadFile,
    session_id: str,
    x_api_key: str = Header(...)
):
    if x_api_key != API_KEY:
        raise HTTPException(status_code=401, detail="Invalid API key")
    # ...
```

**Agent:**
```python
# uploader.py
headers = {"X-API-Key": "votre_api_key"}
resp = requests.post(SERVER_URL, files=files, data=data, headers=headers)
```

---

## 📊 Part 7: Monitoring

### 7.1 Logs Serveur

```bash
# Logs en temps réel
tail -f /var/log/rpa-api.log

# Ou avec systemd
journalctl -u rpa-api -f
```

### 7.2 Statistiques

**Endpoint stats (à ajouter):**
```python
@app.get("/api/traces/stats")
async def get_stats():
    return {
        "total_sessions": len(list(SESSIONS_DIR.iterdir())),
        "total_uploads": len(list(UPLOAD_DIR.glob("*.enc"))),
        "disk_usage_mb": sum(f.stat().st_size for f in SESSIONS_DIR.rglob("*")) / 1024 / 1024
    }
```

---

## 🎯 Checklist Déploiement

### Agent
- [ ] Build exécutables (Windows/macOS/Linux)
- [ ] Tester sur chaque OS
- [ ] Configurer `server_url` production
- [ ] Configurer `encryption_password`
- [ ] Créer installeurs (optionnel)
- [ ] Distribuer aux formateurs

### Serveur
- [ ] Installer dépendances
- [ ] Configurer `ENCRYPTION_PASSWORD`
- [ ] Démarrer serveur (systemd)
- [ ] Configurer HTTPS (Nginx)
- [ ] Configurer firewall
- [ ] Tester endpoint `/api/traces/status`
- [ ] Configurer monitoring

### Test End-to-End
- [ ] Agent → Upload → Serveur
- [ ] Vérifier déchiffrement
- [ ] Vérifier extraction ZIP
- [ ] Vérifier chargement RawSession
- [ ] Vérifier logs

---

## 🚨 Troubleshooting

### Agent ne démarre pas

**Windows:**
- Antivirus bloque → Ajouter exception
- DLL manquantes → Installer Visual C++ Redistributable

**macOS:**
- Permissions refusées → Activer Accessibility + Screen Recording
- "App is damaged" → `xattr -cr agent_v0.app`

**Linux:**
- `xdotool` manquant → `sudo apt-get install xdotool`

### Upload échoue

- Vérifier `server_url` dans config
- Vérifier serveur accessible: `curl https://votre-serveur.com/api/traces/status`
- Vérifier firewall
- Vérifier logs serveur

### Déchiffrement échoue

- Vérifier même `encryption_password` agent/serveur
- Vérifier fichier .enc pas corrompu
- Vérifier version `cryptography` identique

---

## 📞 Support

**Problèmes?**
- Logs agent: `agent_v0/logs/agent_v0.log`
- Logs serveur: `journalctl -u rpa-api`
- GitHub Issues: [lien]

---

**Build et déploiement terminés!** 🎉

Les formateurs peuvent maintenant enregistrer leurs workflows et alimenter le système RPA Vision V3.