From e185dabc4579ecfb4e531bfd599f12a3f4dde326 Mon Sep 17 00:00:00 2001 From: "IETM_FIXE\\ietm6" Date: Tue, 21 Apr 2026 14:41:46 +0200 Subject: [PATCH] =?UTF-8?q?Mise=20=C3=A0=20jour=20de=20l'install.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- INSTALL.md | 338 +++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 287 insertions(+), 51 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index 5075d60..09a852e 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,75 +1,311 @@ # Installation de LoreMindMJ -## Prerequis +Ce document decrit la procedure d'installation de LoreMindMJ. Temps estime : +5 a 10 minutes selon la qualite de la connexion reseau. -- **Docker Desktop** ([Windows](https://www.docker.com/products/docker-desktop/) / [Mac](https://www.docker.com/products/docker-desktop/)) - ou **Docker Engine + Compose v2** (Linux). -- (Optionnel) **[Ollama](https://ollama.com/)** si tu veux un LLM local. - Sinon, une cle API [1min.ai](https://1min.ai) suffit. +## 1. Prerequis -## Installation (5 minutes) +- **Docker Desktop** ([Windows](https://www.docker.com/products/docker-desktop/) / + [Mac](https://www.docker.com/products/docker-desktop/)) ou + **Docker Engine + Compose v2** (Linux). Verification : + ``` + docker --version + docker compose version + ``` + Compose v2 est requis : la commande est `docker compose`, non `docker-compose`. -1. Telecharge `docker-compose.yml` et `.env.example` depuis la [derniere release](https://git.igmlcreation.fr/ietm64/LoreMindMJ/releases) dans un dossier a toi. +- **Un fournisseur LLM**, au choix : + - **[Ollama](https://ollama.com/)** installe sur la machine hote (gratuit, + local, necessite environ 6 Go de RAM libre pour les modeles recommandes). + - **Une cle API [1min.ai](https://1min.ai)** (hebergement cloud, facturation + a l'usage, aucune installation supplementaire requise). -2. Renomme `.env.example` en `.env` et ouvre-le dans un editeur texte. Trois variables sont **obligatoires** : - - `POSTGRES_PASSWORD` : mot de passe de la base (choisis-en un). - - `ADMIN_PASSWORD` : protege l'ecran Parametres de l'appli. Tu le taperas dans une popup du navigateur. - - `BRAIN_INTERNAL_SECRET` : secret interne partage entre les services. Genere une valeur aleatoire : - ``` - openssl rand -hex 32 - ``` - (Sous Windows sans openssl : utilise un generateur en ligne type "random hex string 64 chars".) +- Environ **2 Go d'espace disque** pour les images Docker, auxquels s'ajoute + la taille des modeles Ollama si l'option locale est retenue. - Sans ces trois variables, `docker compose up` refusera de demarrer — c'est volontaire pour eviter un deploiement non-securise par defaut. +## 2. Recuperation des fichiers -3. Dans un terminal, place-toi dans le dossier et lance : - ``` - docker compose up -d - ``` - Le premier demarrage telecharge les images (~500 Mo) et initialise la base. Compte 1-2 minutes. +Telecharger les deux fichiers suivants depuis la +[derniere release](https://git.igmlcreation.fr/ietm64/LoreMindMJ/releases) et +les placer dans un dossier dedie (par exemple `~/loremind/` ou +`C:\Programs\loremind\`) : -4. Ouvre http://localhost:8081 dans ton navigateur. Bon jeu ! +- `docker-compose.yml` +- `.env.example` -## Mise a jour +Le code source n'est pas necessaire : les images sont pre-construites et +publiees sur le registry Gitea `git.igmlcreation.fr` (non Docker Hub). Le +premier `docker compose pull` les telechargera automatiquement. + +## 3. Configuration du fichier `.env` + +Renommer `.env.example` en `.env` et l'ouvrir dans un editeur de texte. **Trois +variables sont obligatoires** ; sans elles, `docker compose up` refusera de +demarrer. Ce comportement est volontaire afin d'eviter tout deploiement +non-securise par defaut. + +### `POSTGRES_PASSWORD` + +Mot de passe de la base de donnees PostgreSQL. Choisir une valeur robuste. +Seuls les conteneurs utilisent cette valeur : il n'est pas necessaire de la +memoriser au-dela du fichier `.env`. + +### `ADMIN_PASSWORD` + +Protege l'ecran **Parametres** de l'application via HTTP Basic. Cette valeur +sera demandee par le navigateur lors de toute modification de la configuration +(changement de modele LLM, saisie de cle API, etc.). Le nom d'utilisateur par +defaut est `admin`, modifiable via la variable `ADMIN_USERNAME`. + +### `BRAIN_INTERNAL_SECRET` + +Secret partage entre le service Java (`core`) et le service Python (`brain`). +Empeche toute requete externe d'atteindre directement le service Brain. +Generer une valeur aleatoire de 64 caracteres hexadecimaux : + +``` +openssl rand -hex 32 +``` + +Sous Windows sans `openssl`, utiliser PowerShell : + +```powershell +-join ((48..57) + (97..102) | Get-Random -Count 64 | % {[char]$_}) +``` + +### Variables optionnelles + +- `WEB_PORT` (defaut `8081`) : port d'ecoute de l'interface web. +- `ADMIN_USERNAME` (defaut `admin`) : identifiant de la popup Parametres. +- `LLM_PROVIDER` (defaut `ollama`) : choix du fournisseur LLM (voir + section 5). + +Les autres variables (`MINIO_USER`/`MINIO_PASSWORD`, `POSTGRES_DB`, +`POSTGRES_USER`) disposent de valeurs par defaut adaptees a un deploiement +personnel et peuvent etre conservees en l'etat. + +## 4. Lancement de la stack + +Depuis le dossier contenant `docker-compose.yml` et `.env` : + +``` +docker compose up -d +``` + +Le premier demarrage telecharge les images (environ 1 a 2 Go au total) et +initialise la base. Compter 2 a 5 minutes selon la qualite de la connexion. +La progression peut etre suivie via : + +``` +docker compose logs -f +``` + +(`Ctrl+C` pour quitter l'affichage ; les services continuent de fonctionner +en arriere-plan.) + +Une fois les services en etat `healthy`, ouvrir **http://localhost:8081** +dans un navigateur. + +### Verification du fonctionnement + +``` +docker compose ps +``` + +Cinq conteneurs doivent apparaitre en etat `Up` ou `healthy` : +`loremind-postgres`, `loremind-minio`, `loremind-core`, `loremind-brain`, +`loremind-web`. Le conteneur `loremind-minio-init` s'arrete automatiquement +apres creation du bucket d'images : ce comportement est normal. + +## 5. Configuration du fournisseur LLM + +### Ollama (local, gratuit) + +Installer Ollama sur la machine hote (pas dans Docker), puis telecharger un +modele : + +``` +ollama pull gemma4:26b +``` + +Dans `.env` : + +``` +LLM_PROVIDER=ollama +LLM_MODEL=gemma4:26b +OLLAMA_BASE_URL=http://host.docker.internal:11434 +``` + +L'adresse `host.docker.internal` permet au conteneur `brain` d'atteindre +Ollama sur la machine hote. Cette resolution est native sous Docker Desktop +(Mac / Windows). Sous Linux, le fichier `docker-compose.yml` declare un +`extra_hosts` equivalent. + +### 1min.ai (cloud, paye) + +Dans `.env` : + +``` +LLM_PROVIDER=onemin +ONEMIN_API_KEY=sk-... +ONEMIN_MODEL=gpt-4o-mini +``` + +### Modification a chaud + +Le fournisseur, le modele et la cle API peuvent etre modifies a chaud depuis +l'ecran **Parametres** de l'application. Les modifications sont persistees +dans un volume Docker et survivent aux redemarrages. Les variables d'env du +fichier `.env` sont uniquement utilisees comme valeurs initiales au premier +demarrage. + +## 6. Mise a jour ``` docker compose pull docker compose up -d ``` -Les donnees (base Postgres, images MinIO, settings Brain) sont dans des volumes Docker et survivent aux mises a jour. +Les donnees (base PostgreSQL, images MinIO, configuration Brain) sont +stockees dans des volumes Docker et survivent aux mises a jour. -## LLM : Ollama ou 1min.ai ? +## 7. Sauvegarde -**Ollama (local, gratuit)** — Edite `.env` : -``` -LLM_PROVIDER=ollama -LLM_MODEL=gemma4:26b -``` -Telecharge le modele au prealable : `ollama pull gemma4:26b`. +Les donnees sont reparties dans trois volumes Docker : -**1min.ai (cloud, paye)** — Edite `.env` : -``` -LLM_PROVIDER=onemin -ONEMIN_API_KEY=sk-... -ONEMIN_MODEL=open-mistral-nemo -``` +- `loremindmj_postgres-data` — ensemble des donnees applicatives (lores, + campagnes, pages, templates, branches narratives, etc.). +- `loremindmj_minio-data` — images uploadees. +- `loremindmj_brain-data` — parametres IA (fournisseur courant, cle API + 1min.ai). -Tu peux aussi changer tout ca a chaud depuis l'ecran Parametres de l'appli. +### Export SQL de la base -## Problemes frequents - -- **Port 8081 deja pris** : change `WEB_PORT=8082` (ou autre) dans `.env`. -- **Ollama injoignable** : verifie qu'Ollama tourne (`ollama serve`) et que le modele est bien telecharge. -- **"set ADMIN_PASSWORD in .env" / "set BRAIN_INTERNAL_SECRET in .env"** au lancement : tu as oublie une des variables obligatoires de l'etape 2. -- **Popup "Ce site vous demande de vous connecter" sur l'ecran Parametres** : c'est normal. Utilise `admin` (ou ce que tu as mis dans `ADMIN_USERNAME`) et ton `ADMIN_PASSWORD`. -- **Tout casser et repartir de zero** : `docker compose down -v` supprime les volumes (attention, perte de donnees). - -## Sauvegarde - -Les donnees sont dans les volumes Docker : `loremindmj_postgres-data`, `loremindmj_minio-data`, `loremindmj_brain-data`. - -Sauvegarde rapide de la base : ``` docker compose exec postgres pg_dump -U loremind loremind > backup.sql ``` + +### Sauvegarde complete des volumes + +Arreter la stack au prealable afin de garantir la coherence des donnees : + +``` +docker compose stop +docker run --rm -v loremindmj_postgres-data:/data -v $(pwd):/backup alpine tar czf /backup/postgres-data.tar.gz -C /data . +docker run --rm -v loremindmj_minio-data:/data -v $(pwd):/backup alpine tar czf /backup/minio-data.tar.gz -C /data . +docker compose start +``` + +Sous Windows PowerShell, remplacer `$(pwd)` par `${PWD}`. + +## 8. Resolution des problemes + +### Port 8081 deja utilise + +Modifier `WEB_PORT=8082` (ou toute autre valeur libre) dans `.env`, puis +relancer : + +``` +docker compose up -d +``` + +### Erreur "set POSTGRES_PASSWORD in .env" (ou variable equivalente) au lancement + +Une des trois variables obligatoires de l'etape 3 est manquante. Verifier le +contenu du fichier `.env`. + +### Popup "Ce site vous demande de vous connecter" sur l'ecran Parametres + +Comportement attendu : il s'agit de l'authentification HTTP Basic. Utiliser +la valeur de `ADMIN_USERNAME` (par defaut `admin`) et celle de +`ADMIN_PASSWORD`. + +### Erreurs `password authentication failed` en boucle dans les logs Postgres + +Si la variable `POSTGRES_PASSWORD` a ete modifiee apres un premier lancement, +le volume Postgres conserve l'ancien mot de passe (initialise une seule fois). +Deux options : + +- **Redemarrer avec un volume vierge** (entraine la perte des donnees) : + ``` + docker compose down -v + docker compose up -d + ``` +- **Modifier le mot de passe en base** sans toucher au volume : + ``` + docker compose exec postgres psql -U postgres + ``` + Puis dans le prompt `psql` : + ```sql + ALTER USER loremind WITH PASSWORD 'valeur_exacte_du_env'; + \q + ``` + Redemarrer ensuite le Core : `docker compose restart core`. + +### Erreur "502 Bad Gateway" ou message d'erreur IA dans l'interface + +Le service Brain ne parvient pas a contacter le fournisseur LLM. Verifier : + +- **Ollama** : `ollama serve` est-il actif ? Le modele est-il telecharge + (`ollama list`) ? La valeur de `LLM_MODEL` correspond-elle exactement au + nom d'un modele liste ? +- **1min.ai** : la cle API est-elle valide ? Le modele existe-t-il ? +- Consulter les logs du Brain : + ``` + docker compose logs brain + ``` + +### Un service ne demarre pas ou reste en etat `unhealthy` + +Consulter les logs du service concerne : + +``` +docker compose logs +``` + +Services disponibles : `postgres`, `minio`, `core`, `brain`, `web`. + +### Redemarrage d'un service apres modification du `.env` + +``` +docker compose up -d +``` + +Redemarrage complet : `docker compose restart`. + +### Remise a zero complete (PERTE DES DONNEES) + +``` +docker compose down -v +``` + +L'option `-v` supprime les volumes. L'ensemble des lores, campagnes, images +et parametres est perdu de maniere definitive. + +### "No such image" ou "pull access denied" au premier lancement + +Le registry Gitea peut necessiter une authentification selon la visibilite +configuree pour les images. Contacter l'editeur du projet. + +## 9. Exposition reseau des services + +- **Interface web** : http://localhost:8081 (port configurable via + `WEB_PORT`). +- **PostgreSQL** : accessible uniquement via le reseau Docker interne, non + expose vers l'hote. +- **MinIO** : accessible uniquement via le reseau Docker interne. Les images + transitent par le reverse-proxy Java sur `/api/images/{id}/content`. Le + binding `127.0.0.1:9000/9001` defini dans `docker-compose.override.yml` + n'est actif qu'en developpement. +- **Brain Python** : accessible uniquement via le reseau Docker interne. + Toute requete doit porter l'en-tete `X-Internal-Secret`, injectee + automatiquement par le Core Java et jamais exposee au navigateur. + +## 10. Desinstallation + +``` +docker compose down -v +docker image rm git.igmlcreation.fr/ietm64/core git.igmlcreation.fr/ietm64/brain git.igmlcreation.fr/ietm64/web +``` + +Supprimer ensuite le dossier contenant `docker-compose.yml` et `.env`.