# Guide d'installation Lea - POC, MVP, production et multi-site

- Date: 2026-06-19
- Statut: version initiale exploitable, a durcir avant production
- Scope: installations Lea/RPA Vision V3 sur DGX + postes ou VM Windows
- Source: etat POC DGX, runbooks coordination, installeur Windows, systemd, dashboard/VWB/worker

## Objectif

Ce document sert de base d'installation reproductible pour plusieurs phases:

1. **POC**: installation controlee sur un site pilote, avec assistance technique forte.
2. **MVP**: installation repetable avec artefacts figes, checklist, rollback et preuves.
3. **Production**: installation industrialisee, secrets par site, supervision, sauvegardes, signature de l'installeur, support.
4. **Multi-etablissement**: meme produit, mais variables reseau, comptes, tokens, politiques de securite et donnees separees par etablissement.

Le principe directeur: une installation Lea ne doit pas dependre de la memoire d'un agent ou d'une session de debug. Elle doit etre executable par une checklist, testable, rollbackable et auditable.

## Architecture cible d'une installation

### Composants cote serveur

| Composant | Role | Port POC | Exposition attendue |
|---|---|---:|---|
| Dashboard Flask | supervision, verite produit, fleet, workflow status | 5001 | LAN/VPN autorise avec auth |
| VWB backend | workflows, anchors, base SQLite VWB | 5002 | local ou LAN controle selon packaging |
| Agent Chat | chat Lea, bulles, feedback temps reel | 5004 | accessible depuis poste/VM Windows |
| Streaming/Fleet | ingestion agent Windows, sessions, API agent | 5005 | accessible depuis poste/VM Windows |
| Upload/API core | API interne upload/traitement | 8000 | loopback par defaut |
| Worker | compilation/apprentissage/replay | n/a | service systemd |
| Ollama/VLM | inference locale | 11434 | local DGX, pas expose sauf decision explicite |
| VM/VNC Windows | console Windows DGX si utilisee | 5902 | tunnel SSH/VPN uniquement |

### Composants cote Windows

| Composant | Role | Artefact |
|---|---|---|
| Lea agent | capture, tray, chat, apprentissage, streaming | `deploy/lea_package` ou installeur Inno |
| `config.txt` | URL serveur, token API, machine id, label utilisateur | genere par dashboard ou installeur |
| Installeur Inno | installation MVP/prod, Python embedded, silent install | `deploy/installer/Lea.iss` |
| VM Windows | poste de test ou execution clinique | VMware, Hyper-V, QEMU standalone ou poste physique |

## Niveaux d'installation

| Niveau | Usage | Acceptable | Interdit |
|---|---|---|---|
| POC labo | tests rapides, validation technique | scripts manuels documentes, tunnel VNC, debug coordonne | secrets reutilises sans trace, actions non consignees |
| POC site | installation pilote chez client | artefact fige, runbook, rollback, preuves | activer reseau/site sans fenetre et rollback |
| MVP | repetition sur plusieurs postes | installeur signe ou controle, config par poste, smoke automatique | ZIP manuel non versionne comme seul chemin |
| Production | support multi-etablissement | CI release, signature, supervision, backups, rotation secrets | `DASHBOARD_AUTH_DISABLED`, tokens partages, ports remote ouverts |

## Fiche site obligatoire

Chaque etablissement doit avoir une fiche separee avant installation.

```text
SITE_ID=
Nom etablissement=
Contact technique=
Contact metier=
Fenetre installation=
Fenetre rollback=

DGX_HOSTNAME=
DGX_IP_LAB=
DGX_IP_SITE=
DGX_PREFIX=
DGX_GATEWAY=
DGX_DNS_1=
DGX_DNS_2=
IPv6=off/on
VLAN=non/oui + id
Interface Ethernet cible=

Dashboard URL=
Streaming URL agent=
Agent Chat URL=
VWB URL=

Windows cible=
Type Windows=poste physique / VMware / Hyper-V / QEMU DGX
Nom machine Windows=
Utilisateur Windows=
Mode acces distant=VNC / RDP / console hyperviseur / aucun

RPA_API_TOKEN=
DASHBOARD_USER=
DASHBOARD_PASSWORD=
ENCRYPTION_PASSWORD=
SECRET_KEY=

Politique retention=
Chemin backup=
Responsable validation GO=
```

Regle: aucun token ou mot de passe d'un site ne doit etre reutilise sur un autre site.

## Pre-requis avant installation

### Pre-requis DGX ou serveur Linux

- OS Linux valide pour le deploiement.
- Acces admin local ou fenetre avec administrateur.
- Python 3.10 a 3.12.
- GPU NVIDIA si inference VLM locale attendue.
- Ollama installe si le mode VLM local l'utilise.
- Repo disponible sur la branche cible, par exemple `poc-dgx` pour le POC.
- Ports internes/externes arbitres avant installation.
- Disque libre suffisant pour sessions, captures, backups et modeles.
- Politique backup validee avant toute migration ou reset.

### Pre-requis Windows

- Windows 10/11.
- Droits suffisants pour installer Lea.
- Acces reseau au DGX sur les ports agent requis.
- Pour MVP/prod, privilegier l'installeur Inno avec Python embedded.
- Pour POC, le ZIP `deploy/Lea_v<version>.zip` reste acceptable si documente.

### Pre-requis securite

- `DASHBOARD_AUTH_DISABLED` interdit hors dev local.
- `RPA_AUTH_DISABLED` interdit hors dev local.
- `RPA_API_TOKEN` obligatoire.
- `DASHBOARD_PASSWORD` obligatoire.
- Remote desktop/VNC/RDP ouverts uniquement en tunnel/VPN, jamais en LAN large par defaut.
- Les secrets sont stockes hors git.
- Le poste Windows doit afficher clairement l'etat d'enregistrement/apprentissage.

## Procedure POC actuelle

Cette section decrit l'etat connu du POC DGX. Elle n'est pas encore le chemin production final.

### 1. DGX - recuperer le code

```bash
git clone <repo> rpa_vision_v3
cd rpa_vision_v3
git checkout poc-dgx
```

Si le DGX contient deja des donnees runtime, ne jamais faire de reset destructif sans backup des chemins suivants:

```text
visual_workflow_builder/backend/instance/workflows.db
visual_workflow_builder/backend/data/
data/training/
data/runtime/
data/workflows
graphify-out/ si l'historique graphe doit etre preserve
```

### 2. DGX - environnement Python

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

### 3. DGX - configuration runtime

Creer `.env.local` depuis le modele:

```bash
cp deploy/systemd/rpa_vision_v3.env.example .env.local
```

Valeurs obligatoires a remplacer:

```text
ENCRYPTION_PASSWORD=CHANGE_ME
SECRET_KEY=CHANGE_ME
RPA_API_TOKEN=CHANGE_ME
DASHBOARD_USER=lea
DASHBOARD_PASSWORD=CHANGE_ME
ENVIRONMENT=production
RPA_PROCESSING_WORKER=external
RPA_API_HOST=127.0.0.1
RPA_DASHBOARD_HOST=0.0.0.0
RPA_VLM_MODEL=gemma4:26b
RPA_GROUNDING_ENGINE=qwen3vl_vllm
VLLM_MODEL=Qwen/Qwen3-VL-4B-Instruct
```

Pour un site, documenter explicitement quels services restent en loopback et quels services sont accessibles depuis la VM/poste Windows. En POC DGX, le dashboard est expose au LAN sur `0.0.0.0:5001` avec auth. En clinique durcie, preferer un reverse proxy HTTPS ou un bind loopback derriere proxy/VPN.

### 4. DGX - services

Services systemd attendus ou equivalents:

```text
rpa-agent-chat.service
rpa-firewall.service
rpa-streaming.service
rpa-vision-v3-api.service
rpa-vision-v3-dashboard.service ou fallback rpa-vision-v3-dashboard-user
rpa-vision-v3-worker.service
rpa-vision-v3-stream-worker.service
rpa-vision-v3-vwb-backend.service
rpa-vision-v3-vwb-frontend.service
rpa-vllm-grounder.service si active
rpa-vision.target
```

Commandes de controle:

```bash
systemctl status rpa-agent-chat.service
systemctl status rpa-firewall.service
systemctl status rpa-streaming.service
systemctl status rpa-vision-v3-dashboard.service
systemctl status rpa-vision-v3-worker.service
systemctl status rpa-vision-v3-stream-worker.service
systemctl status rpa-vision-v3-vwb-backend.service
systemctl status rpa-vision-v3-vwb-frontend.service
systemctl list-units 'rpa*'
```

En POC dev, `svc.sh` reste utilisable:

```bash
./svc.sh status
./svc.sh start
./svc.sh restart api
./svc.sh stop
```

### 5. DGX - modele local

Verifier Ollama et les modeles attendus. Le POC DGX distingue:

- cerveau/lecteur Ollama: par exemple `gemma4:26b` selon `.env.local`;
- grounder VLM via vLLM: `Qwen/Qwen3-VL-4B-Instruct` avec `think=false`.

```bash
curl http://localhost:11434/api/tags
ollama list
# Si le modele site manque:
ollama pull <modele_ollama_site>
```

Ne pas exposer `11434` au LAN sans decision explicite.

### 6. DGX - donnees VWB/apprentissage

Verifier:

```bash
test -f visual_workflow_builder/backend/instance/workflows.db
find visual_workflow_builder/backend/data -maxdepth 3 -type f | head
find data/training -maxdepth 3 -type f | head
```

Endpoints utiles:

```bash
curl -s http://127.0.0.1:5002/health
curl -s http://127.0.0.1:5005/health
curl -s http://127.0.0.1:5001/api/system/status
```

Selon l'auth dashboard, `5001` peut repondre `401`; c'est attendu si l'auth est active.

## Installation Windows

### Chemin POC ZIP

Construire le package:

```bash
./deploy/build_package.sh --clean
./deploy/build_package.sh
```

Copier `deploy/Lea_v<version>.zip` sur la machine Windows, puis:

1. Dezipper.
2. Modifier `config.txt`.
3. Lancer `install.bat`.
4. Lancer `Lea.bat`.

`config.txt` minimum:

```text
RPA_SERVER_URL=http://<DGX_IP>:5005/api/v1
RPA_API_TOKEN=<token_site_ou_poste>
RPA_MACHINE_ID=<site-machine-unique>
RPA_USER_LABEL=<nom_utilisateur_ou_poste>
RPA_BLUR_SENSITIVE=false
RPA_LOG_RETENTION_DAYS=180
```

### Chemin MVP/prod installeur

Le chemin cible est l'installeur Inno Setup:

```bash
./deploy/installer/build_installer.sh
```

Sortie attendue:

```text
deploy/releases/Lea-Setup-v1.0.1.exe
```

Installation silencieuse type:

```cmd
Lea-Setup-v1.0.1.exe /VERYSILENT /CONFIG=C:\temp\enroll.txt /DIR="C:\Lea" /LOG="C:\temp\lea-install.log"
```

`enroll.txt`:

```text
USER_NAME=Prenom Nom
USER_EMAIL=prenom.nom@example.local
USER_ID=EMP-00123
SERVER_URL=http://<DGX_IP>:5005/api/v1
API_TOKEN=<token>
```

Production: l'installeur doit etre signe pour eviter les alertes SmartScreen et faciliter le deploiement IT.

## VM Windows DGX - etat POC et regles

Etat confirme le 2026-06-19:

- Windows 11 ARM DGX fonctionne via QEMU standalone.
- Acces utilisateur via VNC tunnel `localhost:5902`.
- Le runtime actif utilise `disk.qcow2` cote utilisateur `aivanov`.
- La definition libvirt `win11-arm-lea` peut apparaitre arretee pendant que le standalone tourne.

Regles:

- Ne pas demarrer la VM libvirt `win11-arm-lea` pendant que QEMU standalone utilise deja `disk.qcow2`.
- Ne pas lancer deux VM sur le meme disque.
- En standalone, `disk.qcow2` doit etre accessible a l'utilisateur qui lance QEMU, actuellement `aivanov`.
- Si retour libvirt, prevoir de remettre l'ownership attendu par libvirt, par exemple `libvirt-qemu:libvirt-qemu`, apres arret complet du standalone.
- Le VNC doit rester en loopback/tunnel, par exemple `127.0.0.1:5902`, pas en exposition LAN large.

Loose ends a traiter avant MVP:

1. Persister proprement le VNC loopback dans le script original ou dans un wrapper.
2. Decider si le VNC a un password pose automatiquement via monitor, ou pas de password car tunnel obligatoire.
3. Choisir un seul runtime officiel pour la VM DGX: standalone documente ou libvirt corrige.
4. Documenter le rollback disk owner standalone <-> libvirt.
5. Decider et implementer l'auto-start au reboot DGX si la VM Windows doit etre disponible apres redemarrage:
   - script persiste, pas `/tmp/vmvnc.sh`;
   - service systemd `User=aivanov` ou user service avec `loginctl enable-linger`;
   - `After=network-online.target`;
   - garde-fou contre un demarrage libvirt parallele;
   - choix VNC: sans password car loopback+tunnel, ou wrapper qui pose le password via monitor.

## Reseau site

Chaque site doit avoir un plan reseau valide avant installation.

Exemple clinique prepare:

```text
DGX_IP_SITE=192.168.1.178
PREFIX=/24
GATEWAY=192.168.1.243
DNS_1=192.168.1.9
DNS_2=192.168.1.8
IPv6=off
VLAN=non
Interface=Ethernet uniquement
```

Regles:

- Ne pas activer le profil Ethernet site pendant les tests labo sans GO.
- Prevoir un acces local ou une console avant toute bascule reseau.
- Noter le rollback exact avant modification IP.
- Valider depuis Windows: dashboard, chat, streaming.

## Smoke tests d'acceptation

### Serveur

| Test | Attendu |
|---|---|
| `systemctl status rpa-streaming` | actif |
| `systemctl status rpa-vision-v3-dashboard` | actif ou fallback documente |
| `curl :5005/health` | 200/healthy |
| dashboard `:5001` | login/401 ou UI, pas 500 |
| `/api/system/status` | coherent, pas de faux vert |
| `/api/workflows` | workflows VWB visibles |
| worker status | `healthy` ou `idle` non degrade si aucun job |
| ports remote VNC/RDP | fermes au LAN, tunnel only |

### Windows

| Test | Attendu |
|---|---|
| `config.txt` | valeurs site/poste remplacees, aucun `CONFIGURE_ME` |
| lancement Lea | tray visible |
| chat Lea | connexion au DGX |
| capture/apprentissage | demarre avec consentement utilisateur |
| stop apprentissage | session ecrite cote DGX |
| dashboard fleet | machine visible |
| streaming | session recue sur `5005` |

### VWB/apprentissage

| Test | Attendu |
|---|---|
| `workflows.db` | present, backup effectue |
| workflows dashboard | liste chargee |
| anchors | images visibles |
| replay supervise | action ou demande de confirmation, pas de clic non controle |
| worker | session traitee puis retour sain |

## Criteres GO / NO-GO

GO installation site si:

- artefacts versionnes et identifies;
- fiche site complete;
- secrets generes pour le site;
- DGX accessible et services verts;
- Windows connecte au DGX;
- dashboard/VWB/worker coherents;
- ports remote non exposes hors tunnel/VPN;
- rollback documente;
- preuves archivees.

NO-GO si:

- un secret `CHANGE_ME` ou `CONFIGURE_ME` reste en place;
- dashboard auth desactive hors dev;
- `RPA_AUTH_DISABLED=true` hors dev;
- VWB/workflows absents sans decision;
- Windows ne rejoint pas le streaming;
- VM ou poste controle le mauvais DGX;
- deux runtimes VM utilisent le meme disque;
- ports VNC/RDP exposes au LAN sans validation;
- pas de backup `workflows.db` avant reset/deploy.

## Sauvegarde et rollback

Avant chaque installation ou upgrade:

```bash
STAMP=$(date +%Y%m%dT%H%M%S)
mkdir -p .codex_backups/install-$STAMP
cp -a visual_workflow_builder/backend/instance/workflows.db .codex_backups/install-$STAMP/ 2>/dev/null || true
cp -a visual_workflow_builder/backend/data .codex_backups/install-$STAMP/vwb-data 2>/dev/null || true
cp -a data/training .codex_backups/install-$STAMP/training 2>/dev/null || true
cp -a .env.local .codex_backups/install-$STAMP/env.local 2>/dev/null || true
```

Rollback code:

```bash
git fetch origin
git checkout <commit_valide>
systemctl restart rpa-streaming rpa-vision-v3-dashboard rpa-vision-v3-worker rpa-agent-chat
```

Rollback donnees: restaurer uniquement les chemins sauvegardes, jamais faire `git clean -xfd` sur le DGX POC avec donnees runtime non trackees.

## Journal de preuve d'installation

Pour chaque installation, creer un dossier de preuve:

```text
installations/<SITE_ID>/<YYYY-MM-DD>/
  site-sheet.md
  versions.txt
  services.txt
  ports.txt
  dashboard-smoke.txt
  windows-agent-smoke.txt
  vwb-smoke.txt
  backups.txt
  incidents.md
  verdict.md
```

`versions.txt` doit contenir:

```bash
git rev-parse HEAD
git status -sb
python --version
pip freeze | sort
systemctl --version
ollama list
```

## Industrialisation requise avant production

| Sujet | Etat POC | Attendu MVP/prod |
|---|---|---|
| Installeur Windows | Inno disponible | release signee, tests install/desinstall |
| Enrollment | config/token manuel ou dashboard | token par poste, expiration/revocation |
| Secrets | `.env.local` manuel | coffre ou procedure secrete auditee |
| Services | systemd partiel selon DGX | target unique, healthcheck, recover |
| Supervision | dashboard + logs | alerting, retention, export incident |
| Backups | manuels | job planifie, test de restauration |
| VM Windows DGX | standalone VNC manuel fonctionnel | runtime officiel choisi, persiste et auto-start arbitre |
| Multi-site | variables en coordination | fiche site versionnee, aucun secret partage |
| Documentation utilisateur | `LISEZMOI.txt` | guide utilisateur + admin par site |
| Support | agents war-room | procedure support N1/N2/N3 |

## Check-list courte jour d'installation

1. Valider fiche site et fenetre rollback.
2. Verifier artefact serveur et installeur Windows.
3. Generer secrets site/poste.
4. Sauvegarder donnees DGX existantes.
5. Installer ou mettre a jour serveur.
6. Configurer reseau sans perdre l'acces de rollback.
7. Demarrer services.
8. Installer Lea sur Windows.
9. Lancer smoke serveur.
10. Lancer smoke Windows.
11. Tester dashboard, VWB, chat, streaming, worker.
12. Archiver preuves.
13. Donner verdict GO/NO-GO.
14. Si GO, remettre les acces temporaires en mode securise.

## Documents sources

- `README.md`
- `deploy/systemd/rpa_vision_v3.env.example`
- `deploy/lea_package/LISEZMOI.txt`
- `deploy/lea_package/config.txt`
- `deploy/build_package.sh`
- `deploy/installer/README.md`
- `deploy/installer/Lea.iss`
- `docs/coordination/RUNBOOK-DGX-POST-REBOOT-CHECK.md`
- `docs/coordination/RUNBOOK-LEA-LIVE-DRAFT.md`
- `docs/coordination/active/2026-06-19_1418_postaction-windows-dgx-fonctionne.md`
- `docs/coordination/inbox_codex/2026-06-19_1420_claude-to-codex_ACK-STOP-DIAG-VM-LOOSE-ENDS.md`