_Assistant_Lead_Tech/60_playbooks/migration_projet_vers_nuc.md

Playbook — Migration d’un projet vers le NUC

Ce document décrit la procédure standard pour migrer un projet local (Mac / Docker Desktop) vers l’environnement NUC Docker Dev.

Objectifs :

• centraliser l’exécution des conteneurs sur le NUC
• garder le code sur le NUC pour le développement via SSH / VSCode
• uniformiser la structure des projets

---

Architecture cible

Sur le NUC :

/srv/
  projects/        # code des projets
  docker-data/     # volumes persistants
  backups/         # sauvegardes

Exemple pour un projet :

/srv/projects/portfolio

Les volumes Docker doivent vivre dans :

/srv/docker-data/<nom-projet>/

---

Étape 1 — Cloner le projet sur le NUC

Depuis le NUC :

cd /srv/projects
git clone <repo>

Exemple :

git clone git@github.com:xxx/portfolio.git

---

Étape 1b — Initialiser la mémoire projet

Depuis la racine du projet cloné :

cd /srv/projects/<repo>
gen-claude

Cette commande :

• génère CLAUDE.md depuis le template projet
• crée AGENTS.md -> CLAUDE.md
• initialise la mémoire active du projet pour Claude / Codex

---

Étape 2 — Adapter docker-compose

Les projets ne doivent pas dépendre de Docker Desktop.

Principes :

• utiliser des chemins absolus côté NUC pour les volumes
• éviter les volumes implicites Docker

Exemple :

volumes:
  - /srv/docker-data/portfolio/postgres:/var/lib/postgresql/data

---

Étape 3 — Vérifier les dépendances système

Sur la VM docker-dev :

• Docker installé
• Docker Compose disponible
• Node / npm si nécessaire

Vérifier :

docker --version
docker compose version
node -v

---

Étape 4 — Lancer les conteneurs

Depuis le dossier du projet :

docker compose up -d

Vérifier :

docker ps

---

Étape 5 — Migration éventuelle des données

Si le projet utilisait Docker Desktop :

1. exporter la base

pg_dump -U user dbname > dump.sql

2. copier le dump sur le NUC

3. restaurer :

psql -U user dbname < dump.sql

---

Étape 6 — Vérification

Vérifier :

• l’application démarre
• la base de données est accessible
• les migrations fonctionnent
• les logs ne contiennent pas d’erreurs

Commandes utiles :

docker logs <container>
docker compose logs -f

---

Bonnes pratiques

• ne jamais stocker de données persistantes dans /srv/projects
• tous les volumes doivent vivre dans /srv/docker-data
• documenter les migrations importantes

---

Quand utiliser ce playbook

Ce playbook doit être utilisé lorsque :

• un projet Docker Desktop est migré vers le NUC
• un nouveau projet est installé sur le NUC
• un projet doit être reproduit sur un nouvel environnement

---

Outils associés

• scripts/generate_project_claude.sh — initialisation de la mémoire projet (CLAUDE.md + AGENTS.md)