Comment auto-héberger AnythingLLM en 2026 : documents, embeddings et persistance

Un container AnythingLLM peut être au vert alors que la fonctionnalité attendue par les utilisateurs est en panne. Avec AnythingLLM, cette défaillance invisible vient généralement de l’absence du montage de stockage ou d’un changement de modèle d’embedding après l’indexation. Ce guide considère comme test d’acceptation l’action suivante : « ingérer un document, attendre l’embedding, poser une question dont la réponse dépend de ce document et vérifier l’extrait source cité ». Le déploiement est ensuite conçu à rebours à partir de ce résultat.

AnythingLLM joue un rôle précis dans la stack : permettre le chat sur des documents et leur retrieval sans devoir créer un pipeline de toutes pièces. La question à se poser en production n’est donc pas de savoir si le port 3001 répond une fois, mais si l’état, les dépendances et l’adresse publique restent cohérents après un redémarrage, une mise à jour et une restauration.

Ports, processus et services privés

Un schéma utile d’AnythingLLM montre la route publique, le port privé 3001, la limite de l’état et toutes les exigences associées. Indiquez quelles flèches transportent des credentials et lesquelles correspondent à du trafic utilisateur ordinaire. Le contrat réseau d’AnythingLLM repose sur un fournisseur d’embeddings, un fournisseur de LLM et un espace de stockage suffisant pour les documents. Gardez les endpoints privés sur un DNS interne, n’autorisez que les appels sortants nécessaires et attribuez à AnythingLLM un credential de service limité.

Validez le schéma avec une action réelle : ingérez un document, attendez l’embedding, posez une question dont la réponse dépend de ce document et vérifiez l’extrait source cité. Les principales contraintes devraient venir de l’analyse des documents, du débit d’embedding, de la taille du vector store et du contexte envoyé au modèle sélectionné ; surveillez ce parcours plutôt que de considérer toutes les requêtes HTTP comme équivalentes.

Rendez la récupération d’AnythingLLM mesurable

Inventoriez chaque artefact durable : documents, index vectoriels, workspaces et paramètres de l’application. Montez /app/server/storage avant le bootstrap, écrivez des données d’exemple inoffensives, puis remplacez le container pour vérifier que ce chemin est réellement persistant. Incluez les paramètres qui modifient la façon dont les données stockées sont interprétées, et pas uniquement le répertoire le plus volumineux.

Définissez une politique de rétention, copiez les sauvegardes hors de l’hôte et effectuez une restauration en clean room. Le test de récupération d’AnythingLLM est terminé lorsque les documents, les embeddings, l’appartenance aux workspaces et les paramètres des fournisseurs sont restaurés ensemble et permettent de répondre à la même question fondée sur les éléments de preuve. Si les snapshots font partie du plan, utilisez le guide PITR versus snapshot pour documenter ce que chaque mécanisme permet de récupérer.

Définissez la trust boundary d’AnythingLLM

Après la première connexion, vérifiez ce qu’un visiteur anonyme, un utilisateur standard et un administrateur peuvent faire chacun. La défaillance à éviter avec AnythingLLM consiste à considérer la connexion au workspace comme un substitut à l’isolation des provider keys. La politique souhaitée consiste à limiter les membres aux workspaces et à conserver les credentials des fournisseurs de LLM, d’embeddings et de bases de données vectorielles sur le serveur.

Générez JWT_SECRET avec une valeur aléatoire longue ; sa rotation invalide normalement les sessions ou les tokens. Prévoyez donc son impact sur les utilisateurs au lieu de la présenter comme une migration de chiffrement. Séparez les comptes de dépendances des comptes humains, refusez les flux sortants inutilisés lorsque c’est possible et limitez les opérations influencées par l’analyse des documents, le débit d’embedding, la taille du vector store et le contexte envoyé au modèle sélectionné.

Ce qui doit être validé avant l’arrivée des vraies données AnythingLLM

Le release record d’AnythingLLM doit contenir des faits, pas un simple « ça a l’air bon ». Enregistrez le digest de l’image sélectionnée, le checksum de la configuration, le hostname public et le résultat horodaté de l’action suivante : ingérer un document, attendre l’embedding, poser une question dont la réponse dépend de ce document et vérifier l’extrait source cité. Utilisez des données d’exemple hors production afin que cette vérification puisse être exécutée après chaque déploiement.

Validez séparément deux événements du cycle de vie. Le remplacement d’un container doit préserver le fonctionnement normal ; une récupération propre doit montrer que les documents, les embeddings, l’appartenance aux workspaces et les paramètres des fournisseurs sont restaurés ensemble et permettent de répondre à la même question fondée sur les éléments de preuve. Pendant les vérifications, mesurez l’analyse des documents, le débit d’embedding, la taille du vector store et le contexte envoyé au modèle sélectionné, puis conservez le résultat comme enveloppe attendue pour cette version.

Testez également une condition refusée ou invalide : refusez temporairement à l’identité de test l’accès à un fournisseur d’embeddings, à un fournisseur de LLM et à un espace de stockage suffisant pour les documents. AnythingLLM doit échouer de manière diagnostiquable et ne doit pas écraser un état sain. Rétablissez la condition valide, relancez l’échantillon et joignez les logs pertinents après masquage. Ces artefacts fournissent des éléments concrets pour prendre une future décision de rollback.

Créez un container AnythingLLM remplaçable

Une commande minimale est utile lorsqu’elle révèle ce que la plateforme gérera ensuite.

docker run -d \
  --name anythingllm \
  --restart unless-stopped \
  -p 127.0.0.1:3001:3001 \
  -v anythingllm-data:/app/server/storage \
  -e JWT_SECRET=replace-with-a-long-random-value \
  mintplexlabs/anythingllm:latest

Ici, le port 3001 reste privé sur l’hôte et chaque chemin requis est explicite. Ajoutez les paramètres de connexion validés pour un fournisseur d’embeddings, un fournisseur de LLM et un espace de stockage suffisant pour les documents ; utilisez des noms privés pour les services privés. Vérifiez le démarrage à la fois avec les logs et avec la validation propre à l’application : ingérer un document, attendre l’embedding, poser une question dont la réponse dépend de ce document et vérifier l’extrait source cité. Une fois la vérification effectuée, verrouillez la version de l’image afin qu’un remplacement courant ne modifie pas silencieusement le comportement.

Testez AnythingLLM depuis l’extérieur du serveur

Évitez les origins publiques temporaires et permanentes pour AnythingLLM. Utilisez plutôt l’origin HTTPS externe pour l’accès du navigateur et de l’API, faites pointer le nom DNS choisi vers la route de la plateforme et ne faites proxy que vers le port 3001.

Effectuez cette action depuis l’extérieur de l’hôte : ingérez un document, attendez l’embedding, posez une question dont la réponse dépend de ce document et vérifiez l’extrait source cité. Si l’ingress échoue, le guide de dépannage des erreurs 502 couvre les erreurs de port et de listener. Si AnythingLLM reçoit la requête mais que le montage de stockage est absent ou que le modèle d’embedding a changé après l’indexation, les éléments de preuve orientent désormais le diagnostic au-delà du proxy.

Exercices de panne pour AnythingLLM

Créez des dashboards autour de l’analyse des documents, du débit d’embedding, de la taille du vector store et du contexte envoyé au modèle sélectionné. Un graphique du CPU dépourvu du contexte de cette charge ne peut pas expliquer pourquoi AnythingLLM est lent. Ajoutez une vérification synthétique ou planifiée qui tente d’ingérer un document, d’attendre l’embedding, de poser une question dont la réponse dépend de ce document et de vérifier l’extrait source cité à l’aide de données de test inoffensives.

Avant une mise à niveau, tenez compte du risque propre à cette application : changer de modèle d’embedding peut nécessiter une réindexation, tandis que les releases de l’application peuvent migrer les métadonnées des workspaces et des vecteurs. Restaurez une sauvegarde récente dans un déploiement isolé, exécutez-y les migrations et comparez le comportement. Si le montage de stockage est absent ou que le modèle d’embedding a changé après l’indexation, inspectez la limite concernée — origin publique, stockage ou dépendance — avant de modifier des paramètres sans rapport.

Ce que Dockup devrait automatiser pour AnythingLLM

Pour AnythingLLM, Dockup peut créer la route et le certificat TLS, préserver les montages, distribuer les secrets et placer un fournisseur d’embeddings, un fournisseur de LLM et un espace de stockage suffisant pour les documents sur un réseau privé, tout en déployant sur Dockup ou sur des serveurs associés.

La release gate reste toutefois la transaction concrète d’AnythingLLM : ingérer un document, attendre l’embedding, poser une question dont la réponse dépend de ce document et vérifier l’extrait source cité. Vérifiez également la condition de restauration : les documents, les embeddings, l’appartenance aux workspaces et les paramètres des fournisseurs doivent être restaurés ensemble et permettre de répondre à la même question fondée sur les éléments de preuve. Ces deux vérifications montrent si le déploiement fonctionne et s’il peut être récupéré.

Foire aux questions

De quoi AnythingLLM a-t-il besoin pour un déploiement en production ?

Faites passer le container AnythingLLM sur le port 3001 via une seule origin HTTPS. Les exigences réseau associées sont un fournisseur d’embeddings, un fournisseur de LLM et un espace de stockage suffisant pour les documents. Ne considérez pas AnythingLLM comme prêt tant que vous ne pouvez pas ingérer un document, attendre l’embedding, poser une question dont la réponse dépend de ce document et vérifier l’extrait source cité.

Quelles données AnythingLLM doivent être incluses dans une sauvegarde ?

Rendez /app/server/storage persistant et incluez les documents, les index vectoriels, les workspaces et les paramètres de l’application dans le même recovery manifest. Une restauration propre d’AnythingLLM n’est validée que lorsque les documents, les embeddings, l’appartenance aux workspaces et les paramètres des fournisseurs sont restaurés ensemble et permettent de répondre à la même question fondée sur les éléments de preuve.

AnythingLLM a-t-il besoin de HTTPS derrière un reverse proxy ?

Utilisez HTTPS pour l’origin publique d’AnythingLLM et gardez le port 3001 sur la route interne. Appliquez correctement le paramètre d’AnythingLLM : utilisez l’origin HTTPS externe pour l’accès du navigateur et de l’API. Pour AnythingLLM, HTTPS protège les credentials ou le contenu utilisateur pendant leur transit et assure un comportement cohérent des clients sensibles à l’origin.

Comment tester une mise à niveau d’AnythingLLM ?

Restaurez l’état actuel d’AnythingLLM dans un déploiement isolé, appliquez la version candidate et répétez sa transaction d’acceptation. Soyez particulièrement attentif, car changer de modèle d’embedding peut nécessiter une réindexation, tandis que les releases de l’application peuvent migrer les métadonnées des workspaces et des vecteurs. Conservez l’image précédente d’AnythingLLM jusqu’à ce que les limites de migration des données et de rollback soient comprises.