Aller au contenu
Wavertex
Sommaire de la documentation

Installation

Vérifié avec Cortex le 2 octobre 2026

Cortex s’installe sur votre propre infrastructure. L’installation met en place l’interface web, la passerelle et PostgreSQL avec pgvector. Le moteur IA est optionnel et s’ajoute après coup.

Prérequis

  • Docker avec Compose.
  • Node 24 et pnpm 11, installés sur la machine hôte : le script de configuration et les commandes de provisionnement s’exécutent sur l’hôte, pas dans un conteneur.
  • Les ports 3000 (interface web), 4000 (passerelle) et 5432 (PostgreSQL) libres.
  • Un modèle avec lequel converser : un modèle local (Ollama, par exemple) ou le compte d’un fournisseur infonuagique.

Si vous utilisez votre propre instance PostgreSQL plutôt que le conteneur fourni, elle doit être en version 18 ou plus récente, avec pgvector 0.8 ou plus récent installé sur le serveur. Le conteneur fourni (pgvector/pgvector:pg18) respecte ces deux exigences. Pour une instance externe, l’amorçage privilégié doit être fait avant le script : les rôles cortex_owner et cortex_gateway, une base appartenant à cortex_owner et pgvector installé (voir le chapitre « External PostgreSQL » du document DEPLOYMENT du dépôt). Sans cela, le script s’arrête.

Installer avec le script

Le script de configuration sert à une première installation ou à une évaluation. Un déploiement en production demande ses propres clés et réglages : voir Configuration et, dans le dépôt de Cortex, le document DEPLOYMENT.

  1. Clonez le dépôt de Cortex, puis placez-vous à sa racine. Exécutez git clone <adresse du dépôt>, où l’adresse est celle du dépôt Cortex.

  2. Lancez le script de configuration :

    ./scripts/setup-dev.sh

    Il vous demande où tourne PostgreSQL (conteneur fourni ou instance externe), les mots de passe, les ports et la langue de l’interface. Il génère aussi une clé de chiffrement aléatoire si vous le souhaitez. Ensuite, il écrit le fichier .env, installe les dépendances, démarre uniquement le conteneur PostgreSQL (ou, pour une instance externe, vérifie la connexion et la présence de pgvector), exécute les migrations, crée le locataire et le premier compte administrateur, puis propose d’ajouter une destination LLM. Vous pouvez le relancer sans risque : les valeurs d’un .env existant deviennent les réponses par défaut.

  3. Démarrez la pile complète :

    docker compose up -d --build

    Le script ne construit ni ne démarre les conteneurs web et passerelle : cette commande s’en charge. Avec une instance PostgreSQL externe, utilisez plutôt l’override fourni (Docker Compose 2.24 ou plus récent) :

    docker compose -f docker-compose.yml -f docker-compose.external-db.yml up -d --build

Premier démarrage

Ouvrez http://localhost:3000 (ou le port web que vous avez choisi) et connectez-vous avec le courriel et le mot de passe du compte administrateur créé par le script. Ce compte arrive directement sur la console d’administration.

Capture de Cortex : la page de connexion, avec le bouton de connexion SSO et le formulaire courriel et mot de passe
La page de connexion : SSO ou compte local.

Une destination créée par le script est ouverte au seul rôle « Employé », et le compte créé par le script ne porte que le rôle « Administrateur » : pour tester la conversation, connectez-vous avec un compte employé, ou ajoutez le rôle à la destination. Si vous n’avez pas ajouté de destination pendant le script, ajoutez-en une depuis l’entrée « Destinations » de la console d’administration (la page « Destinations LLM »), en l’ouvrant aux rôles concernés, avant de converser : sans destination, personne ne peut écrire de message.

Activer le moteur IA (optionnel)

Le moteur IA est un nœud Python conçu pour n’être joignable que par la passerelle (chaque requête exige son en-tête signé ; l’isolation réseau est une règle de déploiement). Il ajoute :

  • la reconnaissance d’entités nommées dans le DLP (DLP 1.5), par exemple les noms de personnes ;
  • la détection par un modèle local (DLP 2), qui s’appuie sur un serveur compatible OpenAI que vous contrôlez ;
  • l’extraction de texte et les vecteurs de la base de connaissances.

Cortex fonctionne sans lui : le filtrage par motifs et secrets continue de s’appliquer, et aucune fonction essentielle n’en dépend. Le fichier docker-compose.yml de Cortex ne contient pas encore de service pour le moteur : vous construisez son image (docker build -t cortex-ai-engine apps/ai-engine) et vous la lancez vous-même. Le moteur vérifie l’en-tête signé de la passerelle avec une clé publique, CONTEXT_SIGNING_PUBLIC_KEY.

Dans le fichier .env à la racine du dépôt (lu par Compose sur l’hôte), trois variables l’activent, puis recréez le conteneur de la passerelle (docker compose up -d gateway) :

AI_ENGINE_ENABLED=true
AI_ENGINE_URL=http://<adresse du moteur>:8000
CONTEXT_SIGNING_PRIVATE_KEY=<clé privée Ed25519 en base64>

AI_ENGINE_URL est une adresse nue (schéma, hôte, port), sans chemin. Si une valeur est invalide, la passerelle refuse de démarrer. Si le moteur est injoignable, la passerelle continue de servir avec le DLP par motifs. Voir Configuration pour les variables.

Et ensuite