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:

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:

dist\agent_v0.exe

1.2 Build macOS (.app)

Sur une machine macOS:

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:

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:

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:

./dist/agent_v0

⚠️ Dépendances Linux:

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):

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:

# 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

cd server
./start_server.sh

Méthode 2: Uvicorn direct

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:

[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:

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:

curl http://localhost:8000/api/traces/status

Réponse attendue:

{
  "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:

{
  "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:

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

# 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

cd server
./start_server.sh

Terminal 2: Tester agent

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

curl http://localhost:8000/api/traces/sessions

4.2 Test Production (réseau)

Serveur:

# 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):

{
  "encryption_password": "VotreCléSecrète2025",
  "server_url": "https://votre-serveur.com/api/traces/upload"
}

Test upload manuel:

# 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):

; 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:

makensis installer.nsi

5.2 Package macOS

Créer DMG:

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

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

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

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

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

# 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

# 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):

@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.