LibreChat-Kalanda

LibreChat v0.8.7 personnalisé pour Kalanda

Dépôt git.kalanda.tech · LibreChat upstream (GitHub)

---

Table des matières

• Source du projet
• Personnalisations Kalanda
• Architecture des dossiers
• Précautions importantes
• Règles git & CI/CD
• Importer sur le serveur de prod
• Rebuild de l'image & déploiement
• Fichiers de configuration
• Liens utiles

---

Source du projet

Cette base est un fork personnalisé de LibreChat v0.8.7 (un client IA open-source auto-hébergé).

• Version : v0.8.7
• Base officielle : danny-avila/LibreChat (voir README.zh.md pour la doc d'origine)
• Image Docker : construite localement depuis ce code (voir Rebuild)
• Licence du projet d'origine : voir LICENSE

⚠️ Ce dépôt contient le code source personnalisé. Il ne doit pas être confondu avec le dossier de production qui, lui, contient la configuration et les données (voir Architecture).

---

Personnalisations Kalanda

Cette image ajoute/change les éléments suivants par rapport à LibreChat 0.8.7 stock :

Domaine	Changement	Fichier(s)
Boutons	Bouton "Continuer" en orange (#ff6701), indépendant des tokens runtime (règle robuste !important)	client/src/style.css
Logo login	Logo Kalanda sur l'écran de connexion	client/public/assets/logo.png
Composant login	Bouton OpenID (réordonné) + logo + séparateur, disposition centrée	client/src/components/Auth/AuthLayout.tsx, SocialLoginRender.tsx, LoginForm.tsx
Liens légaux	"Politique de confidentialité" & "Conditions d'utilisation" en noir (au lieu de vert)	client/src/components/Auth/Footer.tsx
Texte de bienvenue	"Bienvenue sur votre IA privée" (FR) — clé com_auth_welcome_back	client/src/locales/fr/translation.json
Séparateur "OU"	Séparateur entre boutons sociaux et formulaire	client/src/locales/fr/translation.json, en/translation.json
Thème	Clair par défaut (réversible par l'utilisateur) via pré-charge color-theme='light'	client/index.html
Logo bouton OpenID	Logo Kalanda sur le bouton "Se connecter via …"	client/public/assets/kalanda-openid.png (référencé par OPENID_IMAGE_URL)
Favicons	Icônes Kalanda	client/public/assets/favicon-16x16.png, favicon-32x32.png, apple-touch-icon-180x180.png
Inscription	Désactivée (ALLOW_REGISTRATION=false)	.env (config, pas code)

Les personnalisations sont soit dans le code frontend (buildées dans l'image), soit dans la configuration (.env, appliquée au runtime).

---

Architecture des dossiers

Ne pas confondre les deux rôles. ⚠️ Ne jamais renommer ni déplacer ces dossiers (voir Précautions).

~/librechat/
├── LibreChat/          ← DOSSIER DE PRODUCTION (orchestration + données)
│   ├── docker-compose.yml   → définit les containers (+ volumes montés)
│   ├── .env                 → configuration (secrets, OpenID, port…)
│   ├── librechat.yaml       → config fonctionnelle LibreChat
│   ├── data-node/           → base MongoDB (DONNÉES CRITIQUES)
│   ├── images/ uploads/ logs/ skill/   → volumes de fichiers
│   └── librechat-src/       ← DOSSIER SOURCE (build context uniquement)
│       ├── Dockerfile
│       ├── api/ client/ packages/ …
│       └── (code personnalisé Kalanda)

• LibreChat/ = ce qui tourne (compose + volumes + config). Les données y vivent.
• librechat-src/ = le code source, sert uniquement à construire l'image.

---

Précautions importantes

• 🚫 Ne jamais renommer/déplacer LibreChat/ ni librechat-src/. Les volumes du compose (Mongo ./data-node, images, uploads…) sont montés avec des chemins relatifs au dossier courant. Les renommer rompt le lien vers les données → base vide / images perdues.
• 🛡️ Sauvegarder Mongo avant toute manipulation sur la prod :

  cd ~/librechat
  sudo docker run --rm --network container:chat-mongodb \
    -v "$(pwd)/mongobackup-$(date +%Y%m%d):/dump" \
    mongo:8.0.20 sh -c 'mongodump --db LibreChat --out /dump'
  ls -la ~/librechat/mongobackup-*/*/ | grep .bson   # vérifier
  

• 🔑 Secrets : générer des valeurs uniques dans .env — CREDS_KEY, CREDS_IV, JWT_SECRET, JWT_REFRESH_SECRET, OPENID_SESSION_SECRET, ADMIN_PANEL_SESSION_SECRET. Ne jamais les committer (.env est gitignoré).
• 📄 Fichiers .env et librechat.yaml: ne pas copier la config de dev sur la prod sans vérifier les valeurs.
• 🧹 Après une extraction d'archive macOS, supprimer les fichiers AppleDouble ._* (ils cassent le chargement des modules) :

  cd ~/librechat/librechat-src
  find . -name '._*' -type f -delete
  

---

Règles git & CI/CD

Flux de travail standard

Ce dépôt suit un flux tronc (main = état de prod). Aucune modification non testée n'est poussée directement.

1. Travailler sur une branche ou commit focalisé ; toujours vérifier git status avant tout.
2. Toute modification de code frontend (design, couleurs, logo, texte) doit être commitée ici puis rebuildée en image (voir Rebuild).
3. Ne jamais committer : .env, docker-compose.override.yml, fichiers de données, node_modules, dist, archives .tar.gz. → Utiliser .env.example pour documenter les variables, client/public/assets/ pour les images.
4. Toujours mettre à jour .env.example quand on ajoute une variable d'env.
5. Commit message clair en français/anglais, ex. :

   Kalanda: bouton Continuer en orange + liens légaux noirs
   

6. Après un commit de modif de design, rebuild et tester en local avant de pousser en prod.

Commandes git utiles

# Inspection
git status                      # voir les changements en cours
git diff --stat HEAD            # résumé des modifs
git log --oneline -5            # historique récent

# Commit
git add <fichiers-ciblés>       # ajouter uniquement ce qui est voulu
git commit -m "message clair"

# Pousser
git push origin main

Versioning

• Tagger les versions stables avec un préfixe kalanda-v :

  git tag kalanda-v0.8.7
  git push origin kalanda-v0.8.7
  

---

Importer sur le serveur de prod

1. Préparer un tarball de code propre (depuis le Mac / poste de dev)

Depuis le dossier source (celui-ci), créer une archive sans xattrs macOS ni données/artefacts :

cd /Users/jonah/Downloads/LibreChat-0.8.7
rm -f /tmp/kalanda-src.tar.gz
COPYFILE_DISABLE=1 tar --no-xattrs \
  --exclude='./node_modules' \
  --exclude='./client/dist' \
  --exclude='./.git' \
  --exclude='./.env' \
  --exclude='./images' --exclude='./uploads' --exclude='./logs' --exclude='./skill' \
  -czf /tmp/kalanda-src.tar.gz .

⚠️ Bien mettre --no-xattrs (sinon tar crée des fichiers ._* AppleDouble) ; ne surtout pas exclure les dossiers de code réel (api/server/services/Files/images en particulier).

💡 Pour un changement ciblé sur quelques fichiers, on peut préférer un tarball réduit :

tar --no-xattrs -czf fix.tar.gz client/src/style.css client/public/assets/kalanda-openid.png ...

2. Transférer via scp

ℹ️ Autoriser l'écriture dans le dossier source (une seule fois) : si scp vers librechat-src renvoie une erreur de permission, c'est que le dossier (extrait avec sudo tar) appartient à root. Rendre l'écriture possible pour kalanda :

sudo chown -R kalanda:kalanda ~/librechat/librechat-src

Ceci permet ensuite un scp direct sans copie manuelle intermédiaire. NB : ne pas faire de chown sur le dossier de prod LibreChat/ (montages Docker).

scp /tmp/kalanda-src.tar.gz kalanda@185.124.202.190:/home/kalanda/librechat/librechat-src/

(mot de passe interactif — non automatisable ici)

3. Extraire dans le dossier source (sur le serveur)

cd ~/librechat/librechat-src
sudo tar -xzf kalanda-src.tar.gz
rm kalanda-src.tar.gz
# nettoyage des éventuels fichiers AppleDouble
find . -name '._*' -type f -delete
# vérifier la présence d'un dossier clé
ls api/server/services/Files/images/ | head

---

Rebuild de l'image & déploiement

Le code personnalisé n'existe pas dans l'image officielle : il faut reconstruire l'image localement depuis la source.

1. Build de l'image

cd ~/librechat/librechat-src
sudo docker build -t librechat-kalanda:0.8.7 .

npm run frontend compile le client (Vite) ; prévoir mémoire (NODE_MAX_OLD_SPACE_SIZE, défini dans le Dockerfile). Compte ~5–10 min.

2. Basculer le service api (sans toucher aux données)

Soit modifier ~/librechat/LibreChat/docker-compose.yml — service api, ligne image: :

image: librechat-kalanda:0.8.7   # remplace ghcr.io/danny-avila/librechat:v0.8.7

Soit (rollback plus facile) un override ~/librechat/LibreChat/docker-compose.override.yml :

services:
  api:
    image: librechat-kalanda:0.8.7

3. Relancer

cd ~/librechat/LibreChat
sudo docker compose up -d api          # recrée uniquement api ; Mongo intouché
# variante ultra-prudente :
# sudo docker compose up -d --no-deps api

4. Vérifier

sudo docker ps | grep LibreChat         # image = librechat-kalanda:0.8.7
sudo docker logs -f LibreChat           # attendre "Server listening"
curl -I http://localhost:3080

Puis recharger la page en vidant le cache : Ctrl+Shift+R (le JS/CSS change).

5. Rollback (si besoin)

cd ~/librechat/LibreChat
sudo rm docker-compose.override.yml     # si override utilisé
# OU remettre la ligne image d'origine dans docker-compose.yml
sudo docker compose up -d api

---

Fichiers de configuration

Fichier	Rôle	Commentaire
.env	variables runtime (port, secrets, OpenID, registration)	gitignoré — jamais commité. Voir .env.example
.env.example	modèle documenté des variables	À maintenir à jour
docker-compose.yml	orchestration des containers + volumes	Rollback de prod
librechat.yaml	config fonctionnelle LibreChat (endpoints, agents…)	librechat.example.yaml pour modèle

Variable clé pour le logo OpenID (dans .env de prod) :

OPENID_IMAGE_URL=/assets/kalanda-openid.png

Inscription désactivée (dans .env) :

ALLOW_REGISTRATION=false
ALLOW_SOCIAL_LOGIN=true
ALLOW_SOCIAL_REGISTRATION=false

---

Liens utiles

• Documentation LibreChat officielle : https://docs.librechat.ai
• Dépôt upstream : https://github.com/LibreChat-AI/LibreChat
• Dépôt remote de ce projet : https://git.kalanda.tech/jonah/LibreChat-Kalanda

---

⬆️ Haut de page