Installer et exécuter Odysseus AI : choisir une méthode et vérifier la première connexion

Choisir Docker, le mode natif ou un guide de plateforme

Le projet officiel présente Docker Compose comme un point de départ reproductible pour de nombreux utilisateurs. L’application et les services associés restent dans une pile connue, ce qui facilite un test propre ou une reconstruction. En contrepartie, localhost dans un conteneur n’est pas automatiquement le localhost du navigateur ou de l’hôte.

Le mode natif est intéressant pour contrôler directement les processus, déboguer Python ou profiter d’un comportement propre à la plateforme. Vous devez alors gérer l’environnement Python, les dépendances, les ports et les journaux. Sous Windows, privilégiez le guide dédié : WSL2, Docker Desktop, PowerShell et Ollama peuvent former plusieurs réseaux distincts.

Faire les vérifications avant l’installation

Un premier échec vient souvent de l’environnement. Avant de cloner le dépôt, choisissez l’emplacement de l’application, les dossiers persistants et la place du serveur de modèles. Commencez par une base minimale plutôt que d’ajouter modèle, proxy, réseau local et recherche en même temps.

Réservez de l’espace pour le code, les conteneurs, les journaux, les modèles et les documents. La RAM et la VRAM d’un modèle local sont distinctes des besoins de l’espace de travail. Faites le premier test dans le navigateur local, puis seulement après étudiez le LAN, Tailscale, le proxy inverse ou l’accès public.

• Vérifier Git, Docker Compose ou le runtime natif de la méthode choisie.
• Préparer un dossier persistant pour le dépôt, .env, les volumes, les journaux et les sauvegardes.
• Garder le premier test sur localhost et ne pas utiliser 0.0.0.0 par défaut.
• Noter si Ollama et SearXNG tourneront sur l’hôte, dans Docker ou sur une autre machine.
• Comparer les commandes au README et au guide officiels actuels.

Installer et démarrer l’espace de travail

Pour un premier essai, Docker fournit souvent la base la plus courte et la plus reproductible. Clonez le dépôt officiel, lisez le README actuel, copiez le fichier d’environnement d’exemple s’il existe, puis démarrez Compose. Ne supposez pas qu’un ancien tutoriel ou un numéro de version décrit encore la branche actuelle.

Une installation native suit la même logique, avec davantage de responsabilités sur l’hôte : créer l’environnement Python, installer les dépendances documentées, lancer la configuration puis démarrer le processus. Sous Windows, utilisez le lanceur du projet au lieu de mélanger des commandes Linux et PowerShell.

1. Démarrer la base seule

   N’ajoutez pas en même temps proxy, accès LAN, modèle et recherche. Le premier objectif est un processus sain.

2. Lire les journaux

   Si le navigateur ne se connecte pas, vérifiez d’abord la santé et les logs plutôt que de changer le port au hasard.

3. Noter la branche

   Le projet peut distinguer une branche de développement d’une branche plus stable. Vérifiez le README avant de reprendre une ancienne commande.

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
cp .env.example .env
docker compose up -d --build

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
powershell -ExecutionPolicy Bypass -File .\launch-windows.ps1

git clone https://github.com/odysseus-dev/odysseus.git
cd odysseus
./start-macos.sh

Connecter Ollama et la recherche séparément

Une fois l’espace ouvert, ajoutez le backend du modèle. En mode natif sur le même hôte, localhost peut convenir. Si Odysseus tourne dans Docker et Ollama sur l’hôte, localhost pointe généralement vers le conteneur ; utilisez l’adresse de passerelle décrite dans le guide Docker. Testez depuis le même espace réseau que l’application.

La recherche est une autre frontière de service. Un SearXNG inclus peut être atteint par le nom du service Compose, tandis qu’une instance externe doit être accessible depuis Odysseus. Une page qui s’ouvre ne prouve donc ni l’inférence ni la recherche : faites un petit test de modèle et un test de recherche séparé.

Vérifier la première connexion avant de travailler

La première connexion est un contrôle opérationnel. Ouvrez le port local indiqué par la méthode actuelle, confirmez que la page correspond à l’instance démarrée et remplacez immédiatement le mot de passe administrateur temporaire. En cas de page blanche ou de proxy, revenez à l’adresse locale directe.

Dans Settings, vérifiez ensuite les services voulus. Utilisez une petite tâche sans fichier sensible : demandez un résumé, observez la réponse, lisez le plan et arrêtez-vous si vous ne comprenez pas les changements proposés.

1. Atteindre la page locale

   Utiliser le port affiché par la procédure et les logs actuels, pas une ancienne URL trouvée dans un article.

2. Changer les identifiants

   Remplacer le mot de passe généré avant tout test LAN, VPN ou proxy inverse.

3. Tester le modèle

   Envoyer un prompt court et confirmer le fournisseur et le modèle sélectionnés.

4. Tester le workflow

   Ouvrir un exemple, vérifier le plan et garder l’approbation manuelle au début.

Construire une routine de démarrage fiable

Une exécution fiable sépare la préparation de la machine, le démarrage de l’application, la connexion des services et l’approbation de l’utilisateur. Si tout est mélangé, chaque problème ressemble à une erreur de modèle. Un petit runbook doit conserver la méthode, l’URL locale, la branche ou le commit testé, les endpoints, le dossier de données et la commande d’arrêt.

Cette trace transforme le prochain redémarrage en procédure connue. Elle est particulièrement utile quand Docker, Ollama, SearXNG et un proxy inverse utilisent des espaces réseau différents.

Résoudre les erreurs courantes

Les problèmes de premier démarrage appartiennent généralement à quelques limites : processus non sain, mauvais port, localhost interprété depuis un autre conteneur, service optionnel inaccessible, volume ou identifiant mal compris. Commencez par la plus petite couche qui échoue et ne changez pas plusieurs variables à la fois.

Pour un tutoriel communautaire, comparez toujours branche, port, variables d’environnement et noms de services avec le dépôt officiel. Un guide utile peut néanmoins être ancien.

Mettre à jour sans perdre le contrôle

Aucune commande universelle ne remplace la lecture des instructions actuelles. Avant un pull ou un rebuild, sauvegardez les données importantes, notez la branche ou le commit testé et vérifiez les changements d’environnement ou de services. Volumes, documents et identifiants rendent un rebuild potentiellement stateful.

Avec Docker, arrêtez et inspectez la pile avant de la recréer. En natif, conservez l’environnement et les changements compris, puis mettez les dépendances à jour volontairement. Avant de sortir de localhost, préparez authentification, HTTPS, contrôles réseau et retour arrière.