Installation locale (WSL2) — stack RAG

Guide d'onboarding développeur pour faire tourner codexia + le cœur RAG (telaria/rag-bundle) sur une machine de dev. Objectif : parité avec le VPS et un démarrage en quelques commandes.

Pourquoi WSL2 et pas Windows natif ? Le cœur RAG charge sqlite-vec via Pdo\Sqlite::loadExtension(). Sous Windows natif, ce chargement d'extension SQLite depuis PHP est fragile/indisponible ; sous WSL2 Ubuntu, c'est le même chemin que le VPS (vec0.so + loadExtension, validé en prod). On évite ainsi un environnement de dev qui diverge de la prod. → pilotage/coordination.md (décision 2026-05-26).

Voir aussi : guides/deployment.md §11 (déploiement VPS de l'IA), specs/ia-coeur.md, tutos/ia/index-vectoriel-sqlite-vec.md, tutos/ia/microservice-embeddings-python.md.

Vue d'ensemble

Trois briques, comme en prod :

L'index et les embeddings sont des artefacts dérivés : on ne les versionne pas, on les régénère avec app:rag:ingest.

1. Prérequis WSL2

Depuis PowerShell (Windows), installer WSL2 + Ubuntu si besoin :

wsl --install -d Ubuntu
wsl --set-default-version 2

La suite se déroule dans le terminal Ubuntu (WSL2).

sudo apt update && sudo apt upgrade -y

2. PHP 8.5+ et extensions SQLite

Cible : PHP 8.5 ou supérieur. Selon la distrib WSL2 :

• Ubuntu 26.04 LTS (Plucky) → apt install php ramène PHP 8.5 (parité VPS stricte).
• Ubuntu 26.04 LTS+ → apt install php ramène PHP 8.5 (validé en réel : boot/ingest/search OK, composer >=8.4 passe).
• Pour rester strict en 8.4 quelle que soit la distrib : passer par le PPA d'Ondřej Surý (sudo add-apt-repository ppa:ondrej/php && sudo apt update) et installer php8.4-* explicitement.

# Variante « version de la distrib » (Ubuntu 26.04 LTS → 8.4, 26.04 → 8.5) :
sudo apt install -y php-cli php-sqlite3 php-mbstring php-xml \
  php-curl php-intl php-zip unzip git

# Variante « 8.4 strict » (PPA Ondřej) :
# sudo apt install -y php8.4-cli php8.4-sqlite3 php8.4-mbstring php8.4-xml \
#   php8.4-curl php8.4-intl php8.4-zip unzip git

Vérifier que pdo_sqlite et sqlite3 sont chargés (indispensables au cœur RAG) :

php -m | grep -E 'pdo_sqlite|sqlite3'
php --version       # 8.4.x ou 8.5.x

Composer :

sudo apt install -y composer    # ou installeur officiel get.composer.org

3. Extension sqlite-vec (locale)

Identique au VPS — release loadable (github.com/asg017/sqlite-vec), pas un paquet apt :

sudo mkdir -p /usr/local/lib/sqlite-vec
cd /tmp
# adapter <ver> à la dernière release
curl -L -o sqlite-vec.tar.gz \
  https://github.com/asg017/sqlite-vec/releases/download/v<ver>/sqlite-vec-<ver>-loadable-linux-x86_64.tar.gz
tar xzf sqlite-vec.tar.gz
sudo cp vec0.so /usr/local/lib/sqlite-vec/vec0.so

C'est ce chemin qu'on pointera via RAG_SQLITE_VEC_PATH (cf. §6). La validation se fait à l'ingest/search (§7).

⚠️ Rappel ia-coeur.md §3.4 : la recherche kNN exige l'extension chargée dans PHP. En WSL2 (comme sur le VPS) c'est le cas — pas de repli « indexation outillée » à prévoir ici.

4. Le microservice telaria-embeddings

Option A — docker-compose (recommandé)

Le dépôt telaria-embeddings fournit son image. Le compose.yaml de dev (cf. §5) lève le service ; on peut aussi le lancer seul :

docker compose up -d embeddings
curl http://127.0.0.1:8001/health     # {"status":"ok","model":"...","dim":768}

Docker tourne dans WSL2 (Docker Desktop avec intégration WSL2, ou docker.io installé dans la distrib). Le premier démarrage télécharge le modèle intfloat/multilingual-e5-base (~1,1 Go) ; monter un volume pour le cache HF_HOME évite de re-télécharger à chaque up.

Option B — venv Python (sans Docker)

Voir tutos/ia/microservice-embeddings-python.md. En résumé :

cd telaria-embeddings
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
uvicorn app:app --host 127.0.0.1 --port 8001

Dans les deux cas le service écoute en local sur :8001 — jamais exposé publiquement.

5. Orchestration dev (compose.yaml) — onboarding « 1 commande »

Un compose.yaml à la racine de codexia peut lever le microservice (l'app PHP restant lancée via symfony serve ou php -S, qui se rechargent à chaud) :

services:
  embeddings:
    image: ghcr.io/<owner>/telaria-embeddings:latest   # ou build: ../telaria-embeddings
    ports:
      - "127.0.0.1:8001:8001"
    volumes:
      - hf-cache:/home/app/.cache/huggingface     # persiste le modèle (~1,1 Go)
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://127.0.0.1:8001/health"]
      interval: 10s
      timeout: 3s
      retries: 5

volumes:
  hf-cache:

docker compose up -d        # le microservice est prêt quand /health passe

Le volume hf-cache est l'équivalent local du HF_HOME sur disque du VPS : il garde le modèle entre deux up pour ne pas re-télécharger 1,1 Go.

6. Configuration de codexia

cd codexia
composer install
cp .env .env.local

Variables RAG dans .env.local (mêmes clés que la prod) :

RAG_EMBEDDING_URL=http://127.0.0.1:8001
RAG_DB_PATH=%kernel.project_dir%/var/rag/index.sqlite
RAG_SQLITE_VEC_PATH=/usr/local/lib/sqlite-vec/vec0.so

Les autres réglages (model, dimension, chunk, retrieval.k, source_root) sont dans config/packages/telaria_rag.yaml. Aucune clé Claude en local pour le cœur (retrieval seul).

Corpus documentaire

Comme sur le VPS, le corpus = telaria-doc cloné dans docs/ (= rag.source_root) :

git clone <url-telaria-doc> docs/

7. Amorçage de l'index

Microservice up (/health OK) → indexer puis tester :

php bin/console app:rag:stats             # diagnostic (index, microservice)
php bin/console app:rag:ingest            # construit var/rag/index.sqlite (--full = complet)
php bin/console app:rag:search "RGPD"     # vérifie la recherche kNN

L'index vit dans var/rag/ (gitignored). Pour repartir de zéro : rm -rf var/rag/* && app:rag:ingest --full.

En local, pas de piège de droits var/rag/ (un seul utilisateur, pas de www-data distinct comme sur le VPS — cf. deployment.md §11.4). C'est l'avantage du dev mono-utilisateur.

L'UI de diagnostic est sur /admin/rag (mode dégradé si le microservice est down : bannière « index indisponible », l'app reste up).

8. Lancer l'application

symfony serve -d            # ou : php -S 127.0.0.1:8000 -t public/

App sur http://127.0.0.1:8000, microservice sur :8001. Accéder à /admin/rag pour l'état du RAG.

8.1 DB minimale pour tester l'UI /admin/rag en local

L'UI /admin/rag (ROLE_ADMIN) suppose un user authentifié → il faut une DB applicative côté codexia. Pour le RAG seul, la DB n'est pas nécessaire (la CLI app:rag:* tourne sans elle). Si tu veux quand même valider l'UI :

• Option rapide (override SQLite) — ajouter dans .env.local :

  DATABASE_URL="sqlite:///%kernel.project_dir%/var/app.db"
  

  puis :

  php bin/console doctrine:database:create
  php bin/console doctrine:migrations:migrate --no-interaction
  # créer un admin de dev (commande applicative codexia) :
  php bin/console app:user:create-admin   # adapter selon la console réelle
  

  Convient à du smoke-test UI ; pas de parité prod (MySQL).
• Option parité (MariaDB en docker-compose) — prérequis PHP : ajouter le driver MySQL (sinon could not find driver au migrate) :

  sudo apt install -y php-mysql        # ou php8.4-mysql / php8.5-mysql selon §2
  

  Puis étendre le compose.yaml (§5) :

  services:
    db:
      image: mariadb:11
      environment:
        MARIADB_DATABASE: codexia
        MARIADB_USER: codexia
        MARIADB_PASSWORD: codexia
        MARIADB_ROOT_PASSWORD: root
      ports:
        - "127.0.0.1:3306:3306"
      volumes:
        - db-data:/var/lib/mysql
  volumes:
    db-data:
    hf-cache:
  

  .env.local : DATABASE_URL="mysql://codexia:codexia@127.0.0.1:3306/codexia?serverVersion=mariadb-11.0.0&charset=utf8mb4". Puis doctrine:migrations:migrate.

Dans les deux cas, l'index RAG (var/rag/index.sqlite) reste indépendant de la DB applicative.

Récapitulatif « machine neuve »

# 1. WSL2 + PHP 8.5 (§1-2)  2. sqlite-vec (§3)  — une fois
docker compose up -d                         # microservice (§4-5)
cd codexia && composer install
cp .env .env.local                           # + clés RAG (§6)
git clone <url-telaria-doc> docs/
php bin/console app:rag:ingest               # amorçage (§7)
symfony serve -d                             # go (§8)

Dépannage