Aller au contenu principal

Installer la Navin Platform à partir des paquets OS

Cette page installe le paquet navin-platform : l'API Control Plane (port 8080), son worker et le portail (port 3300) en services systemd durcis regroupés par navin-platform.target, avec une base PostgreSQL locale. Elle est réalisée par un administrateur système disposant de sudo. Comptez une heure pour un premier serveur, hors serveurs OpenBao et Keycloak de la banque.

Deux chemins mènent au même résultat : l'installateur guidé navin-install (une commande, contrôles d'abord) ou le gestionnaire de paquets du système (étape par étape, ci-dessous).

Avant de commencer​

  • Système, vérifié avec cat /etc/os-release :

    • Ubuntu 24.04 (x86_64), paquet navin-platform_<version>_amd64.deb ;
    • RHEL, Rocky, Alma, Oracle Linux ou CentOS Stream 9 (x86_64), paquet navin-platform-<version>-1.el9.x86_64.rpm ;
    • Arch Linux (x86_64), paquet navin-platform-<version>-1-x86_64.pkg.tar.zst.

    Debian, RHEL 8 et RHEL 10 ne sont pas pris en charge pour le paquet de la plateforme (ils le sont pour l'agent de nœud) : voir Compatibilité OS.

  • Droits : un compte avec sudo ; systemd actif.

  • Ressources : 2 CPU, 4 Gio de mémoire (8 conseillés), 20 Gio libres pour /var, 4 Gio pour /opt (Dimensionnement).

  • Un nom d'hôte complet qui se résout, et une horloge synchronisée.

  • Les dépôts du système (ou le miroir de la banque) : PostgreSQL 15 ou plus récent et Node.js 18.18 ou plus récent.

  • Ports 8080 et 3300 libres, 9464 pour les métriques du worker (Ports réseau).

  • Pour la production : un serveur OpenBao, les clés de signature dans OpenBao, un proxy inverse TLS devant l'API et le portail (TLS).

Option A : installateur guidé​

L'archive hors ligne de votre famille contient navin-install, les paquets et leur SHA256SUMS.

sha256sum -c navin-install-<version>-<famille>.tar.gz.sha256
tar xzf navin-install-<version>-<famille>.tar.gz
cd navin-install-<version>-<famille>
sudo ./navin-install preflight standalone
sudo ./navin-install standalone --openbao-url https://<openbao-host>:8200 --openbao-token-file /root/openbao.token

<famille> : debian (Ubuntu), rhel ou arch. <version> : la version, par exemple 1.0.0.

preflight affiche OK, WARN ou FAIL par contrôle et ne change rien. standalone installe les paquets système, PostgreSQL (socket local seulement), le Navin Manager (https://<fqdn>:8460), l'agent de l'hôte, puis la plateforme. Code de sortie 0 : tout est sain ; 2 : la plateforme attend ses réglages de production (lancez navin-platform check, complétez-les, relancez la même commande) ; 1 : un échec, avec la correction à l'écran et le détail dans /var/log/navin-install.log. --profile evaluation change les refus en avertissements, pour un essai seulement. Le guide complet est os/install/README.fr.md.

Option B : gestionnaire de paquets​

Étapes​

  1. Ajouter le dépôt Navin. Le dépôt sert les paquets signés ; sans lui, le gestionnaire de paquets ne trouve pas navin-platform. Les fichiers clients sont produits par os/repo.sh --sign à côté de la clé publique.

    Ubuntu 24.04 :

    sudo install -m 0644 navin-archive-keyring.gpg /usr/share/keyrings/navin-archive-keyring.gpg
    sudo install -m 0644 navin.sources /etc/apt/sources.list.d/navin.sources
    sudo apt update

    Famille RHEL 9 :

    sudo curl -fsSo /etc/yum.repos.d/navin.repo https://<hote-du-depot>/rhel/navin.repo
    sudo dnf makecache

    Arch Linux :

    sudo pacman-key --add navin-archive-keyring.asc
    sudo pacman-key --lsign-key <empreinte-de-la-cle>
    cat navin.conf | sudo tee -a /etc/pacman.conf
    sudo pacman -Sy

    <hote-du-depot> : nom d'hôte du serveur web (ou du bucket S3, d'Artifactory, Nexus, Satellite, Pulp) où le responsable de release a publié l'arborescence os/repo produite par os/repo.sh --url https://<hote-du-depot>. C'est la même adresse pour apt, dnf et pacman. <empreinte-de-la-cle> : empreinte indiquée dans navin.conf.

    Résultat attendu : apt-cache policy navin-platform, dnf info navin-platform ou pacman -Si navin-platform affiche la version.

    En cas d'échec : vérifiez le proxy du gestionnaire de paquets et la date de l'hôte (contrôle de signature).

  2. Activer les flux de modules (famille RHEL seulement). Le flux PostgreSQL par défaut de RHEL 9 est le 13 ; le schéma exige PostgreSQL 15 ou plus récent et le portail Node.js 18.18 ou plus récent.

    sudo dnf module enable -y postgresql:16 nodejs:20

    Résultat attendu : dnf module list postgresql marque 16 [e].

    En cas d'échec : le dépôt AppStream manque au miroir ; ajoutez-le.

  3. Installer PostgreSQL et le paquet. L'installation crée le compte navin-platform, le venv depuis le wheelhouse hors ligne du paquet, les réglages /etc/navin-platform/platform.env avec une clé maîtresse aléatoire et le premier administrateur du portail, puis la base locale quand PostgreSQL est présent (navin-platform-db local).

    sudo apt install postgresql navin-platform               # Ubuntu 24.04
    sudo dnf install postgresql-server navin-platform        # famille RHEL 9
    sudo pacman -S postgresql navin-platform                 # Arch Linux

    Résultat attendu : les dernières lignes affichent soit navin-platform: services started, soit navin-platform: services enabled, not started: the settings are not complete yet.

    En cas d'échec : the local database could not be configured signifie que PostgreSQL n'a pas démarré ; vérifiez systemctl status postgresql, puis lancez sudo navin-platform-db local.

  4. Compléter les réglages. Un nouvel hôte est configuré pour la production (EAI_ENVIRONMENT=prod) : les services ne démarrent qu'une fois toutes les règles de production respectées. Listez ce qui manque :

    sudo navin-platform check

    Chaque ligne problem: ... nomme un réglage et ce qui est attendu. Modifiez /etc/navin-platform/platform.env (valeurs écrites CLE='valeur') ; la référence commentée est /etc/navin-platform/platform.env.example. Les ajouts habituels sur un hôte de production :

    EAI_OPENBAO_URL='https://<openbao-host>:8200'
    EAI_OPENBAO_TOKEN='<jeton>'
    EAI_CONTEXT_SIGNING_KEY_REF='openbao:eai/context#private_key'
    EAI_AUDIT_SEAL_SIGNING_KEY_REF='openbao:eai/audit-seal#private_key'
    EAI_AUDIT_PAYLOAD_KEK='openbao-transit'
    EAI_RAG_EMBEDDING_MODEL='bge-m3-vllm'
    EAI_MEMORY_EMBEDDING_MODEL='bge-m3-vllm'
    NAVIN_PORTAL_API_URL='<control-plane-url>'
    EAI_CORS_ORIGINS='https://<navin-host>'
    EAI_ALLOWED_HOSTS='<control-plane-host>'
    EAI_TRUSTED_PROXIES='10.0.0.10/32'

    <jeton> : jeton OpenBao de la plateforme. 10.0.0.10/32 : adresse de votre proxy inverse TLS. Chaque réglage est décrit dans la référence de configuration.

    Résultat attendu : navin-platform check affiche navin-platform check: ok.

    En cas d'échec : la ligne nomme le réglage ; une URL de base sans TLS se corrige à l'étape 5.

    astuce

    Sur un hôte d'essai sans OpenBao, EAI_ENVIRONMENT='staging' démarre les services et se contente de journaliser les problèmes de production. Jamais en production.

  5. Déplacer la base vers le serveur PostgreSQL de la banque (facultatif). La production exige une URL de base avec sslmode=require, verify-ca ou verify-full. La base locale par socket n'utilise pas TLS.

    sudo navin-platform-db external \
      'postgresql://navin_platform:<mot-de-passe>@<pg-host>:5432/navin_platform?sslmode=verify-full' \
      'postgresql://navin_platform_api:<mot-de-passe>@<pg-host>:5432/navin_platform?sslmode=verify-full'

    La première URL est le compte administrateur (migrations, worker), la seconde le compte d'exécution de l'API (membre de eai_runtime, sans droit DDL).

    Résultat attendu : les migrations s'appliquent sur le nouveau serveur ; sudo navin-platform-db status les liste comme appliquées.

    En cas d'échec : les URL précédentes reviennent. journalctl -t navin-platform-db donne la raison (sans les mots de passe).

  6. Démarrer les services.

    sudo systemctl start navin-platform.target
    systemctl status navin-platform-api navin-platform-worker navin-platform-portal

    Résultat attendu : les trois unités sont active (running). L'API applique les migrations en attente avant chaque démarrage (ExecStartPre=python -m eai.migrate) ; le worker refuse de démarrer tant qu'une migration est en attente.

    En cas d'échec : journalctl -u navin-platform-api -n 100 affiche unsafe production settings: et les règles en défaut.

  7. Activer le worker média (hôte GPU, facultatif). navin-platform-media-worker.service est installé mais non activé.

    echo "NAVIN_MEDIA_WORKER_ARGS='--kind stt'" | sudo tee -a /etc/navin-platform/platform.env
    sudo systemctl enable --now navin-platform-media-worker

    Résultat attendu : systemctl status navin-platform-media-worker est active (running).

Vérifier​

curl -fsS http://127.0.0.1:8080/readyz
navin-platform version
sudo navin-platform status

Sortie attendue : "status": "ready", la version du paquet et du Control Plane, et chaque migration applied. Ouvrez ensuite le portail et connectez-vous (Première configuration).

Fichiers du paquet​

CheminContenu
/etc/navin-platform/platform.envRéglages de chaque unité (0640 root:navin-platform), créés à la première installation
/etc/navin-platform/platform.env.exampleRéférence commentée des réglages, rafraîchie par les mises à niveau
/opt/navin-platform/venvVenv Python, reconstruit depuis le wheelhouse hors ligne à chaque installation ou mise à niveau
/usr/share/navin-platformContrats, catalogue, migrations SQL (EAI_REPO_ROOT), build du portail, wheelhouse
/var/lib/navin-platformDonnées et copie du portail avec l'URL de l'API du site
/var/log/navin-platformDossier de journaux accessible en écriture aux services (ils journalisent dans le journal : journalctl -u navin-platform-api)
/usr/bin/navin-platformmigrate, status, check, version
/usr/sbin/navin-platform-dblocal, external, status, check, migrate

Les services tournent sous navin-platform avec un système en lecture seule (ProtectSystem=strict), sans capacité, sans élévation de privilèges et avec un filtre d'appels système.

Étapes suivantes​

Dépannage​

SymptômeCauseCorrection
dnf refuse postgresql-server >= 15Flux de module par défaut 13sudo dnf module enable -y postgresql:16 nodejs:20
apt ne peut pas installer python3.12Ce n'est pas Ubuntu 24.04Utilisez Ubuntu 24.04 ; Debian n'est pas pris en charge pour le paquet de la plateforme
pacman refuse une mise à niveau de PythonLe paquet dépend du Python pour lequel il a été construitInstallez d'abord la version Navin construite pour le nouveau Python
navin-platform: ... is not readableCommande lancée sans le groupeLancez-la avec sudo, ou en membre de navin-platform
Le portail répond mais affiche « L'API Control Plane est injoignable »NAVIN_PORTAL_API_URL n'est pas l'URL des navigateursFixez-la, puis sudo systemctl restart navin-platform-portal
Le worker reste activatingUne migration est en attente (eai.migrate --check)sudo navin-platform-db migrate