128 lines
6.3 KiB
Markdown
128 lines
6.3 KiB
Markdown
# PROTOCOL-INFRA — Regles operationnelles infra
|
|
|
|
## Protocole post-deployement (OBLIGATOIRE)
|
|
|
|
Apres tout deployement reussi ou probleme resolu, avant de cloturer la mission :
|
|
|
|
1. Creer un runbook dans le repo Gitea bolbol/nas-runbooks
|
|
- Ecrire UNIQUEMENT dans le dossier hermes-[identite]/
|
|
- Utiliser le template /opt/data/RUNBOOK-TEMPLATE.md
|
|
- La section "Ce qui NE fonctionne PAS" est OBLIGATOIRE
|
|
|
|
2. Poster une note NyoraNotes
|
|
- Tags : [infra, runbook]
|
|
- Contenu : resume du probleme, solution, lien runbook Gitea
|
|
|
|
3. Mettre a jour _INDEX.md dans nas-runbooks
|
|
- Ajouter l entree dans le tableau de l instance
|
|
|
|
4. git add . && git commit && git push vers Gitea
|
|
|
|
## Regle de contribution
|
|
- Ecriture : chaque instance ecrit UNIQUEMENT dans son dossier hermes-[nom]/
|
|
- Lecture : tous les dossiers sont accessibles en lecture
|
|
- Le runbook sans les echecs n a pas de valeur — toujours documenter les tentatives infructueuses
|
|
|
|
## Acces Gitea nas-runbooks
|
|
URL clone : http://192.168.100.33:3232/bolbol/nas-runbooks.git
|
|
Dossier local suggere : /opt/data/workspace/nas-runbooks/
|
|
|
|
---
|
|
|
|
## REGISTRE DES SERVICES — Mise a jour obligatoire
|
|
|
|
Le fichier /volume1/docker/ports-registry.md est la source de verite de l'etat du NAS.
|
|
Il contient deux sections distinctes a maintenir en permanence :
|
|
|
|
### 1. SERVICES ACTIFS (en tete du fichier)
|
|
Mise a jour OBLIGATOIRE a chaque installation OU desinstallation :
|
|
- Installation : ajouter la ligne avec statut ACTIF, port, domaine, notes
|
|
- Desinstallation : changer le statut en "DESINSTALLE JJ/MM/AAAA", liberer le port
|
|
- Ne JAMAIS supprimer une ligne — les services desinstalles restent visibles avec leur date
|
|
|
|
### 2. Historique des modifications (fin du fichier)
|
|
Ajouter une ligne datee pour CHAQUE action :
|
|
- Format : | AAAA-MM-JJ | ACTION | Port | Service |
|
|
- Actions a documenter : Deploiement, DESINSTALLATION, Migration, Changement de port
|
|
|
|
### Verification avant documentation
|
|
Avant de marquer un service comme DESINSTALLE, TOUJOURS verifier :
|
|
curl --max-time 4 http://172.17.0.1:<PORT> -o /dev/null -w "HTTP %{http_code}"
|
|
Si le port repond → le service est encore actif → NE PAS marquer DESINSTALLE
|
|
|
|
### Chemin du fichier
|
|
- Copie locale NAS : /volume1/docker/ports-registry.md
|
|
- Copie nas-runbooks : /volume1/docker/nas-runbooks/common/ports-registry.md
|
|
- Les deux doivent rester synchronisees (copier l'un vers l'autre apres modification)
|
|
- Push Gitea obligatoire apres toute modification
|
|
|
|
|
|
---
|
|
|
|
## Skills transverses — deploiement automatique sur les 3 instances
|
|
|
|
Quand une lecon apprise doit etre appliquee automatiquement par l agent (pas juste documentee pour lecture humaine), la deployer comme skill actif plutot que de compter sur un rappel manuel a chaque fois :
|
|
|
|
1. Creer data/skills/<nom-skill>/SKILL.md sur les 3 instances (hermes-tt, hermes-nyora, hermes-perso), avec un frontmatter description contenant les mots-cles qui doivent declencher le skill
|
|
2. Supprimer le cache .skills_prompt_snapshot.json (racine data/ et data/.hermes/) sur les 3 instances pour forcer la regeneration de l index
|
|
3. Redemarrer les 3 containers hermes-agent-* (via socket Docker /var/run/docker.sock depuis mcp-nas, ou Portainer)
|
|
4. Documenter quand meme via le protocole standard (runbook common/, _INDEX.md, note NyoraNotes) — le skill rend la regle automatique, le runbook garde la tracabilite
|
|
|
|
Exemples deployes le 02/07/2026 : desactivation des skills concurrents a nyora-doc-api (docx/pdf/pptx/xlsx), et skill generation-contenu-volumineux (chunking obligatoire pour eviter la troncature DeepSeek V4 Flash sur les taches lourdes).
|
|
|
|
---
|
|
|
|
## Verification obligatoire avant toute lecture/ecriture sur nas-runbooks depuis mcp-nas
|
|
|
|
Git est ABSENT du container mcp-nas (confirme le 02/07/2026). Toute ecriture sur
|
|
bolbol/nas-runbooks depuis une session mcp-nas passe par l API Gitea (curl + token,
|
|
PUT/POST /api/v1/repos/bolbol/nas-runbooks/contents/<chemin>, avec le sha courant
|
|
recupere par un GET prealable) — jamais par un dossier local suppose a jour.
|
|
|
|
Piege decouvert le 02/07/2026 : /mnt/docker/nas-runbooks etait un clone git reel
|
|
mais sur branche locale master, alors que le remote n a qu une branche main. 14
|
|
commits locaux (15-23 juin, jamais pousses) contenaient du contenu reel absent du
|
|
remote. Cause probable : le binaire git a disparu de mcp-nas avant l etape push.
|
|
Fix applique : recuperation des 14 fichiers via l API vers main, _INDEX.md corrige,
|
|
clone local renomme en nas-runbooks.STALE-clone-local-jamais-pousse-20260702
|
|
(conserve pour inspection, plus utilise comme source).
|
|
|
|
Regle : avant de lire ou modifier un fichier sous /mnt/docker/nas-runbooks (ou tout
|
|
repo Gitea) depuis mcp-nas, verifier d abord via l API que le contenu local
|
|
correspond au remote reel :
|
|
GET /api/v1/repos/bolbol/<repo>/branches
|
|
GET /api/v1/repos/bolbol/<repo>/contents/<chemin>
|
|
Si un vrai clone git fonctionnel est necessaire (multi-fichiers, historique),
|
|
le faire depuis le Mac ou git est present, chemin partage /Volumes/docker ==
|
|
/volume1/docker.
|
|
|
|
## gstack (garrytan/gstack) — decision actee le 02/07/2026
|
|
|
|
Installation prevue sur le futur MacBook M5 Pro via Claude Code natif, PAS sur
|
|
hermes-perso (mem_limit container 600m incompatible Chromium/Playwright, routing
|
|
Sonnet/Opus incompatible regle DeepSeek exclusif Hermes, bug upstream #2015
|
|
AskUserQuestion/clarify non resolu sur --host hermes). Detail complet :
|
|
common/GSTACK-EVALUATION-MACBOOK-VS-HERMES.md.
|
|
|
|
## Piege .env vs docker-compose.yml — decouvert le 03/07/2026
|
|
|
|
Ajouter une variable au .env d un service NE SUFFIT PAS si le
|
|
docker-compose.yml declare un bloc environment: qui whiteliste
|
|
explicitement chaque variable transmise au container (cas
|
|
d hermes-platform/docker-compose.yml). Une variable absente de ce bloc
|
|
n atteint jamais le container meme si elle est correcte dans le .env.
|
|
|
|
Regle : pour toute nouvelle variable d integration (cle API, URL de
|
|
service), toujours verifier ET modifier les deux fichiers :
|
|
1. .env (definition de la valeur)
|
|
2. docker-compose.yml, bloc environment: du/des service(s) concerne(s)
|
|
(transmission de la valeur au container)
|
|
|
|
Verification post-fix : docker exec <container> env | grep <VAR> sur
|
|
le container recree.
|
|
|
|
Cas reel : NYORA_DOC_API_KEY manquante des deux fichiers pour les 3
|
|
instances Hermes -> 401 sur nyora-doc-api. Detail complet :
|
|
common/nyora-doc-api-hermes-guide.md, section "Panne corrigee le
|
|
03/07/2026".
|