# RUNBOOK — Accès Docker complet pour les 3 instances Hermes (29/08/2026)

## Contexte
Les agents Hermes (tt/nyora/perso) n'avaient qu'un seul volume monté
(`data:/opt/data`), aucun accès au socket Docker, aucune capacité de créer
ou déployer quoi que ce soit en dehors de leur bac à sable. Demande de
Nabil : chaque instance doit pouvoir écrire des projets ET les déployer
elle-même (`docker compose up`), sans intervention.

## Changements appliqués (docker-compose.yml de hermes-platform)
Pour chacun des 3 services `hermes-agent-{tt,nyora,perso}` :
- Nouveau volume dédié, un par instance, aucun partage entre elles :
  `/volume1/docker/hermes-{instance}-projects:/opt/projects`
  (créé avec `chown 1026:100`, cohérent avec HERMES_UID/GID)
- `/var/run/docker.sock:/var/run/docker.sock`
- `group_add: ["65538"]` (GID du groupe `docker` sur l'hôte NAS)

L'entrypoint de l'image (`nousresearch/hermes-agent`) détecte automatiquement
le socket monté et crée lui-même un groupe `hostdocker` (GID 65538) — le
`group_add` explicite est donc redondant avec ce comportement mais ne fait
pas de mal, gardé en défense.

## Sécurité — à comprendre avant de reproduire ailleurs
Monter le socket Docker donne à l'agent un accès **root-équivalent sur l'hôte
NAS** : n'importe quel conteneur qu'il crée peut monter n'importe quel chemin
du host, y compris en root. Le dossier `/opt/projects` dédié est une
commodité d'organisation, pas la vraie frontière de sécurité — celle-ci a
déjà disparu dès que le socket est monté. Décision prise en connaissance de
cause par Nabil (délégation complète, cohérent avec le même choix déjà fait
pour claude-oversight sur le VPS).

## Piège rencontré pendant le déploiement
`sed` inséré `group_add:` immédiatement après la ligne d'ancrage sur
l'instance `tt`, qui a — contrairement à nyora/perso — d'autres volumes
après le premier (archive PJ nyora-notes-tt, montage lecture seule
hermes-mail-browser). Résultat : `group_add:` a coupé la liste `volumes:`
en plein milieu, cassant le YAML (Docker a tenté d'interpréter un chemin de
volume comme nom de groupe). Toujours vérifier qu'un bloc `volumes:` n'a
pas d'entrées supplémentaires après le point d'insertion avant d'utiliser
un anchor-based sed — `group_add:` doit atterrir après la DERNIÈRE entrée
`volumes:`, pas après la première.

## Recréation — commande utilisée
Best0f/claude-ops n'ont pas de lecture sur `.env` (600, contient les clés
API) donc `docker compose` ne peut pas s'exécuter directement depuis leur
session. Contournement : conteneur `docker:cli` éphémère, root, avec le
projet et le socket montés au même chemin exact que l'original (pour que
Compose retrouve le bon nom de projet et les réseaux existants) :

    docker run --rm \
      -v /volume1/docker/hermes-platform:/volume1/docker/hermes-platform \
      -v /var/run/docker.sock:/var/run/docker.sock \
      -w /volume1/docker/hermes-platform \
      docker:cli sh -c 'docker compose up -d <service>'

Recréer un seul service à la fois, jamais tous en même temps sur une
première tentative — le redémarrage de la connexion email peut prendre
jusqu'à ~2min30 (contre ~1min habituellement) sans que ce soit une panne,
juste plus lent. Le healthcheck échoue plusieurs fois avant de passer au
vert ; ce n'est pas un signal d'échec tant que les logs ne montrent pas
d'erreur.

## Vérification post-déploiement
Toujours tester avec l'utilisateur réel de l'agent, pas root :
    docker exec --user hermes hermes-agent-<instance> sh -c 'id; docker ps'
`id` doit montrer le groupe `hostdocker` (GID 65538), `docker ps` doit
lister les conteneurs du NAS.