# RUNBOOK — Mise à jour des 3 instances Hermes (NAS DS920+)

**Dernière opération** : 2026-06-15
**Opérateur** : Claude Code (via SSH Best0f@192.168.100.33:22222)
**Périmètre** : hermes-tt, hermes-nyora, hermes-perso

## Architecture réelle (IMPORTANT)
Les 6 conteneurs (3 agents + 3 workspaces) sont pilotés par **UN SEUL** compose :
`/volume1/docker/hermes-platform/docker-compose.yml` (projet Docker `hermes-platform`).
Des `docker-compose.yml` existent AUSSI dans chaque sous-dossier `hermes-<i>/` mais
ils ne sont PAS utilisés par le runtime (voir « Ce qui NE fonctionne PAS »).
Vérifier la provenance via :
`docker inspect <c> --format "{{index .Config.Labels \"com.docker.compose.project.config_files\"}}"`

## Règle IP
- SSH depuis le Mac : 192.168.100.33:22222
- curl/git exécutés via SSH sur le NAS : 127.0.0.1
- Depuis lintérieur dun container : 172.17.0.1
- UID/GID volumes data/ : **1026:100** (obligatoire, sinon PermissionError — cf RUNBOOK-HERMES-UID)

## Images avant → après (2026-06-15)
| Instance | Conteneur | Image | Avant | Après |
|----------|-----------|-------|-------|-------|
| tt | hermes-agent-tt | nousresearch/hermes-agent:latest | 882e06b1ad23 (build 14/06 22:07) | **4d326de7174f (build 15/06 18:03)** |
| nyora | hermes-agent-nyora | nousresearch/hermes-agent:latest | 882e06b1ad23 | **4d326de7174f** |
| perso | hermes-agent-perso | nousresearch/hermes-agent:latest | 882e06b1ad23 | **4d326de7174f** |
| tt | hermes-workspace-tt | ghcr.io/outsourc-e/hermes-workspace:latest | ac411feadfe5 (08/05) | ac411feadfe5 (inchangé — pas de MAJ) |
| nyora | hermes-workspace-nyora | ghcr.io/outsourc-e/hermes-workspace:latest | ac411feadfe5 | ac411feadfe5 (inchangé) |
| perso | hermes-workspace-perso | ghcr.io/outsourc-e/hermes-workspace:latest | ac411feadfe5 | ac411feadfe5 (inchangé) |

Digest agent après : nousresearch/hermes-agent@sha256:474477ad6066d1acc4ca3ae870302568ec3bc6772d12e554f150822f33475f0f

**Résultat** : seuls les 3 AGENTS avaient une image plus récente. Les 3 workspaces
nont PAS été recreate (image identique → rien à mettre à jour).

## Anomalie corrigée
Avant : lagent perso tournait sous le nom `b7f6e6ac8bbf_hermes-agent-perso`
(collision de nom héritée dun `docker compose up` lancé dans le sous-dossier perso).
Le `compose up --force-recreate hermes-agent-perso` depuis le compose RACINE a
réclamé le nom propre `hermes-agent-perso`. Anomalie éliminée (plus aucun
conteneur à préfixe hash).

## Commandes exactes utilisées (via SSH, 127.0.0.1)
```bash
D=/usr/local/bin/docker
cd /volume1/docker/hermes-platform

# 1. Pull (service par service, mais image agent partagée par les 3)
$D compose pull hermes-agent-tt hermes-workspace-tt
# Comparer digest avant/après — ne recreate que si plus récent

# 2. Backup data/ (point de rollback)
TS=$(date +%Y%m%d_%H%M%S)
for i in tt nyora perso; do cp -r hermes-$i/data hermes-$i/data.bak_$TS; done

# 3. Supprimer les locks Telegram (sinon "token already in use")
find /volume1/docker/hermes-platform -name "telegram-bot-token-*.lock" -delete

# 4. Recreate AGENT par AGENT (jamais simultané), healthy avant le suivant
for i in tt nyora perso; do
  $D compose up -d --force-recreate hermes-agent-$i
  sleep 40
  stat -c "%u:%g" hermes-$i/data        # DOIT = 1026:100
  $D inspect hermes-agent-$i --format "{{.State.Health.Status}}"  # DOIT = healthy
done

# 5. Vérif UI
for p in 3010 3020 3030; do curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:$p/; done
```
Backup de cette opération : `data.bak_20260615_191734` (dans chaque hermes-<i>/).

## Ce qui NE fonctionne PAS (pièges rencontrés)
- **NE PAS** lancer `docker compose up` dans un sous-dossier `hermes-<i>/` : les
  compose par instance réutilisent les MÊMES `container_name` → collision → conteneur
  renommé avec préfixe hash (`b7f6e6ac8bbf_...`). Toujours utiliser le compose RACINE.
- **git absent** du host DSM ET des containers (linux-mcp-nas) : pour committer un
  runbook, utiliser l**API Gitea** (PUT/POST /api/v1/repos/bolbol/<repo>/contents/...)
  en basic auth bolbol, PAS `git push`.
- Les workspaces navaient pas de nouvelle image : les recreate aurait été inutile
  (interruption sans gain). Toujours comparer les digests avant de recreate.
- Le `find ... -delete` des locks balaie aussi les `data.bak_*` : sans conséquence
  (les locks seraient supprimés au rollback de toute façon).

## Procédure de ROLLBACK (par instance)
```bash
D=/usr/local/bin/docker
cd /volume1/docker/hermes-platform
$D compose stop hermes-agent-<inst>
rm -rf hermes-<inst>/data && mv hermes-<inst>/data.bak_20260615_191734 hermes-<inst>/data
chown -R 1026:100 hermes-<inst>/data
# Repointer sur lancienne image si besoin : retag 882e06b1ad23 en :latest
# $D tag 882e06b1ad23 nousresearch/hermes-agent:latest
$D compose up -d --force-recreate hermes-agent-<inst>
```