Héberger LibreChat soi-même pour votre propre application façon ChatGPT

LibreChat est une interface web open source façon ChatGPT qui parle à OpenAI, Anthropic, Google et des dizaines d’autres fournisseurs de modèles (ou à un modèle local) via vos propres clés API, au lieu de faire passer vos conversations par le propre produit de clavardage d’un tiers. La seule chose dont il a besoin et qui ne correspond à aucun des modules Postgres ou Redis habituels de Railyard, c’est MongoDB, et c’est là que la plupart des tentatives d’auto-hébergement déraillent. À la fin de ce guide, vous aurez LibreChat et MongoDB qui tournent ensemble derrière HTTPS, avec de vrais secrets générés au lieu des valeurs par défaut, et une sauvegarde que vous pourrez restaurer.

Ce qu’il vous faut

• Un serveur avec Docker et le plugin Compose. Un Hetzner CX23 (2 vCPU, 4 Go de RAM, 40 Go NVMe, 5,99 €/mois hors TVA) fait tourner LibreChat et MongoDB confortablement, puisque l’inférence de modèle se passe réellement sur les serveurs du fournisseur, pas les vôtres.
• Un domaine ou sous-domaine pointé vers l’adresse IP du serveur.
• Au moins une clé API de fournisseur de modèle (OpenAI, Anthropic, ou tout autre fournisseur pris en charge par LibreChat), ajoutée une fois que l’application tourne.
• Un accès SSH au serveur.

Étape 1 : générer les vrais secrets

LibreChat est livré avec des valeurs d’espace réservé pour ses secrets JWT et de chiffrement des identifiants qui fonctionnent pour un essai local mais qui ne sont pas sécuritaires à utiliser en production. Quatre valeurs ont besoin de vraies données uniques : un secret JWT, un secret de rafraîchissement JWT, une clé de chiffrement des identifiants, et son vecteur d’initialisation. Les deux derniers ont des exigences de longueur exactes que les autres n’ont pas, CREDS_KEY doit être une clé de 32 octets (64 caractères hexadécimaux), et CREDS_IV exactement un IV de 16 octets (32 caractères hexadécimaux), sinon le chiffrement AES-CBC propre à LibreChat lance algorithm.iv must contain exactly 16 bytes au démarrage :

openssl rand -hex 32   # JWT_SECRET
openssl rand -hex 32   # JWT_REFRESH_SECRET
openssl rand -hex 32   # CREDS_KEY (32 bytes)
openssl rand -hex 16   # CREDS_IV (16 bytes)
openssl rand -hex 24   # MONGO_PASSWORD

mkdir -p /opt/librechat
cat > /opt/librechat/.env <<'EOF'
JWT_SECRET=paste-the-first-value-here
JWT_REFRESH_SECRET=paste-the-second-value-here
CREDS_KEY=paste-the-third-value-here
CREDS_IV=paste-the-fourth-value-here
MONGO_PASSWORD=paste-the-fifth-value-here
EOF
chmod 600 /opt/librechat/.env

Étape 2 : écrire le fichier Compose

services:
  librechat:
    image: ghcr.io/danny-avila/librechat:v0.8.7
    restart: unless-stopped
    env_file: .env
    depends_on:
      - mongo
    environment:
      MONGO_URI: mongodb://librechat:${MONGO_PASSWORD}@mongo:27017/LibreChat?authSource=admin
      DOMAIN_CLIENT: https://chat.yourdomain.com
      DOMAIN_SERVER: https://chat.yourdomain.com
      ALLOW_REGISTRATION: "true"
    volumes:
      - librechat_uploads:/app/uploads
    expose:
      - "3080"

  mongo:
    image: mongo:7
    restart: unless-stopped
    environment:
      MONGO_INITDB_ROOT_USERNAME: librechat
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD}
    volumes:
      - librechat_mongo_data:/data/db

  caddy:
    image: caddy:2
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - caddy_data:/data
      - caddy_config:/config
    depends_on:
      - librechat

volumes:
  librechat_uploads:
  librechat_mongo_data:
  caddy_data:
  caddy_config:

Ce guide fixe v0.8.7, la version stable actuelle au moment de l’écriture. MONGO_URI transporte le nom d’utilisateur et le mot de passe avec lesquels MongoDB a été initialisé à l’étape 1, avec authSource=admin, puisque l’utilisateur root est créé dans la base admin, pas dans LibreChat. DOMAIN_CLIENT et DOMAIN_SERVER ont tous les deux besoin de l’URL HTTPS exacte à laquelle les utilisateurs rejoindront l’application ; LibreChat les utilise pour construire les cookies et les règles CORS, donc une divergence ici se manifeste par un échec de connexion déroutant plutôt que par une erreur de configuration évidente. ALLOW_REGISTRATION est à true par défaut dans l’image en amont, et compte ici puisque LibreChat n’a aucune autre façon intégrée de créer le premier compte, la connexion sociale est aussi désactivée par défaut, donc ce n’est pas optionnel avant l’étape 4.

Vérifiez que le fichier s’analyse :

docker compose config

Étape 3 : pointer le DNS, ajouter Caddy, démarrer la pile

chat.yourdomain.com {
	reverse_proxy librechat:3080
}

docker compose up -d

docker compose ps
curl -I https://chat.yourdomain.com

Vous devriez voir les deux services à l’état Up et le curl retourner HTTP/2 200 avec un certificat valide.

Étape 4 : créer votre compte, puis verrouiller la porte

Visitez https://chat.yourdomain.com, inscrivez-vous via le formulaire d’inscription normal, et confirmez que vous pouvez vous connecter. Une fois que chaque compte dont vous avez besoin existe, désactivez l’inscription :

environment:
  ALLOW_REGISTRATION: "false"

docker compose up -d librechat

Étape 5 : ajouter un fournisseur de modèle

LibreChat lui-même n’est jamais livré avec une clé API de modèle ; c’est un client pour des fournisseurs que vous apportez vous-même. Ajoutez votre clé comme variable d’environnement, OpenAI comme exemple :

environment:
  OPENAI_API_KEY: ${OPENAI_API_KEY}

Ajoutez OPENAI_API_KEY=your-real-key à .env, puis relancez docker compose up -d librechat. Ouvrez l’application, choisissez le fournisseur dans le menu déroulant de modèles, et envoyez un message. Vous devriez recevoir une vraie réponse, pas une erreur à propos d’une clé manquante ou invalide.

Étape 6 : sauvegarder MongoDB et les téléversements

Les conversations, les comptes et les identifiants chiffrés vivent tous dans MongoDB ; les fichiers téléversés vivent sur le volume librechat_uploads.

cat > /opt/librechat/backup.sh <<'EOF'
#!/bin/sh
cd /opt/librechat
TIMESTAMP=$(date +%Y%m%d-%H%M%S)
docker compose exec -T mongo mongodump --authenticationDatabase admin \
  -u librechat -p "${MONGO_PASSWORD}" --db LibreChat --archive --gzip > backups/mongo-$TIMESTAMP.archive.gz
find backups -mtime +14 -delete
EOF
mkdir -p /opt/librechat/backups
chmod +x /opt/librechat/backup.sh
(crontab -l 2>/dev/null; echo "0 3 * * * /opt/librechat/backup.sh") | crontab -

Lancez-le une fois à la main et vérifiez que ça a fonctionné : ./backup.sh && ls -lh backups. Vous devriez voir un fichier .archive.gz daté. La restauration se fait avec mongorestore --authenticationDatabase admin -u librechat -p "$MONGO_PASSWORD" --archive=path/to/file --gzip, exécutée de la même façon via docker compose exec. Copiez les sauvegardes en dehors du serveur ; perdre à la fois le volume MongoDB actif et sa seule sauvegarde veut dire que chaque conversation et chaque identifiant sauvegardé disparaissent.

Étape 7 : mettre à niveau

docker compose pull librechat
docker compose up -d librechat

LibreChat exécute automatiquement ses propres migrations de données contre MongoDB au démarrage quand c’est nécessaire. Vérifiez les notes de version pour la version vers laquelle vous allez avant un saut de plusieurs versions, puisqu’un changement cassant au schéma de chiffrement des identifiants serait la seule catégorie qui vaille la peine d’être lue en premier.

Le raccourci : avec Railyard

Tout ce qui précède, MongoDB comme seul entrepôt de données que LibreChat ne peut vraiment pas partager avec les modules Postgres ou Redis de Railyard, les secrets JWT et de chiffrement des identifiants générés au lieu d’être laissés par défaut, le volume de téléversements, est aussi ce que le modèle de pile LibreChat de Railyard configure pour vous. Connectez un serveur, puis choisissez LibreChat dans le catalogue de modèles : app.railyard.run/deploy?stack=librechat. Railyard génère JWT_SECRET, JWT_REFRESH_SECRET, CREDS_KEY et le CREDS_IV de 16 octets pour vous aux bonnes longueurs, branche automatiquement la chaîne de connexion de MongoDB, et émet le HTTPS pour votre domaine ; vous ajoutez quand même votre propre clé de fournisseur de modèle par la suite, comme à l’étape 5 ci-dessus.

Voyez déployer avec un bouton et bases de données et sauvegardes pour savoir comment les modèles et les données persistantes fonctionnent sur la plateforme de façon plus générale.

Dépannage

La connexion fonctionne mais rien ne semble persister entre les redémarrages. Confirmez que librechat_mongo_data est un vrai volume nommé dans la sortie de docker compose ps -a, pas un volume anonyme qui a été nettoyé ; ça remonte habituellement à un docker compose down -v exécuté par accident plus tôt, qui retire les volumes en même temps que les conteneurs.

algorithm.iv must contain exactly 16 bytes au démarrage. CREDS_IV n’a pas été généré à exactement 16 octets (32 caractères hexadécimaux). Relancez openssl rand -hex 16 de l’étape 1 et vérifiez que la valeur dans .env fait exactement 32 caractères, pas tronquée ni rembourrée.

Le formulaire d’inscription retourne un 403. ALLOW_REGISTRATION est à false et aucun compte n’existe encore, un problème de l’œuf et la poule si vous l’avez désactivé trop tôt. Remettez-le à true, créez les comptes dont vous avez besoin, puis désactivez-le à nouveau comme à l’étape 4.

Le menu déroulant de modèles montre un fournisseur mais chaque message échoue. La clé API pour ce fournisseur n’est pas définie, est invalide, ou a épuisé son crédit du côté du fournisseur lui-même ; vérifiez docker compose logs librechat pour l’erreur en amont précise, LibreChat relaie généralement le message du fournisseur tel quel.

Le HTTPS ne s’émet pas. docker compose logs caddy montrant des erreurs ACME répétées signifie presque toujours que le DNS de l’étape 3 ne s’est pas propagé ou pointe vers la mauvaise IP.

FAQ

Puis-je faire tourner plus d’un fournisseur de modèle à la fois ? Oui, ajoutez autant de clés API de fournisseurs que vous voulez comme variables d’environnement ; les utilisateurs choisissent quel modèle utiliser par conversation depuis le même menu déroulant.

Est-ce que LibreChat conserve mes conversations chez le fournisseur du modèle ? Non, le fournisseur ne voit que la requête que vous lui envoyez ; LibreChat conserve lui-même l’historique des conversations dans votre propre MongoDB, le fournisseur n’est pas une seconde copie de vos données.

Puis-je faire tourner un modèle local au lieu d’une API hébergée ? Oui, LibreChat prend en charge n’importe quel point de terminaison compatible OpenAI, y compris des serveurs d’inférence locaux, pointés via une configuration de point de terminaison personnalisé plutôt qu’une clé API de fournisseur.

Pourquoi MongoDB spécifiquement, quand tout le reste sur Railyard est Postgres ou Redis ? Le schéma et les motifs de requête propres à LibreChat sont construits autour du modèle documentaire de MongoDB depuis le départ ; ce n’est pas un choix que fait ce guide ou Railyard, c’est ce qu’exige le projet en amont.

Que se passe-t-il si je perds le serveur sans sauvegarde ? Chaque conversation, compte et identifiant sauvegardé disparaît ; il n’y a aucun chemin de récupération vers des données MongoDB qui n’ont jamais été sauvegardées ailleurs, ce qui explique pourquoi l’étape 6 n’est pas optionnelle en pratique.

Une fois les vrais secrets en place et l’inscription verrouillée, un LibreChat auto-hébergé disparaît essentiellement dans le fond. Le travail continu, c’est l’habitude de sauvegarde de l’étape 6 et l’ajout du fournisseur de modèle que vous voulez réellement utiliser.