feats : automatisation des process

60_playbooks/bootstrap_projet_docker.md

@@ -0,0 +1,184 @@
+# Playbook — Bootstrap d’un projet Docker sur le NUC
+
+Ce document décrit la procédure standard pour **initialiser un nouveau projet Docker** sur l’environnement NUC (`docker-dev`).
+
+Objectifs :
+
+- garantir une structure cohérente entre les projets
+- centraliser les volumes persistants
+- préparer le projet pour le développement via VSCode Remote / SSH
+
+---
+
+# Architecture standard du NUC
+
+Tous les projets suivent la structure suivante :
+
+```
+/srv/
+  projects/        # code source des projets
+  docker-data/     # volumes persistants Docker
+  backups/         # sauvegardes
+```
+
+Exemple pour un projet `portfolio` :
+
+```
+/srv/projects/portfolio
+/srv/docker-data/portfolio/
+```
+
+---
+
+# Étape 1 — Cloner le projet
+
+Depuis la VM `docker-dev` :
+
+```
+cd /srv/projects
+git clone <repo>
+cd <repo>
+```
+
+Exemple :
+
+```
+git clone git@github.com:xxx/portfolio.git
+```
+
+---
+
+# Étape 2 — Préparer les volumes persistants
+
+Créer le dossier dédié au projet :
+
+```
+mkdir -p /srv/docker-data/<nom-projet>
+```
+
+Exemples :
+
+```
+/srv/docker-data/portfolio/postgres
+/srv/docker-data/portfolio/uploads
+```
+
+Principe :
+
+- **aucune donnée persistante ne doit vivre dans le repo Git**
+- tous les volumes doivent être externalisés dans `/srv/docker-data`
+
+---
+
+# Étape 3 — Adapter le docker-compose
+
+Les services doivent utiliser les volumes du NUC.
+
+Exemple :
+
+```yaml
+services:
+  postgres:
+    image: postgres:17
+    volumes:
+      - /srv/docker-data/portfolio/postgres:/var/lib/postgresql/data
+```
+
+Bonnes pratiques :
+
+- éviter les volumes anonymes
+- préférer les chemins absolus
+
+---
+
+# Étape 4 — Préparer la base de données (si nécessaire)
+
+Si le projet utilise la base partagée :
+
+```
+psql -U postgres_su
+```
+
+Créer :
+
+```
+CREATE USER <user> WITH PASSWORD '<password>';
+CREATE DATABASE <db> OWNER <user>;
+```
+
+---
+
+# Étape 5 — Initialiser la mémoire projet
+
+Dans le repo :
+
+1. copier le template :
+
+```
+70_templates/projet_CLAUDE.md
+```
+
+2. créer le fichier :
+
+```
+CLAUDE.md
+```
+
+3. créer le symlink pour Codex :
+
+```
+ln -s CLAUDE.md AGENTS.md
+```
+
+Ce fichier servira de **mémoire active du projet**.
+
+---
+
+# Étape 6 — Lancer l’environnement
+
+Depuis le dossier du projet :
+
+```
+docker compose up -d
+```
+
+Vérifier :
+
+```
+docker ps
+```
+
+---
+
+# Étape 7 — Vérification
+
+Contrôler :
+
+- que les conteneurs démarrent correctement
+- que les volumes sont bien montés
+- que la base de données est accessible
+
+Commandes utiles :
+
+```
+docker compose logs -f
+docker logs <container>
+```
+
+---
+
+# Bonnes pratiques
+
+- garder les volumes hors du repo
+- documenter la stack dans `CLAUDE.md`
+- vérifier les ports exposés
+
+---
+
+# Quand utiliser ce playbook
+
+Ce playbook doit être utilisé lorsque :
+
+- un **nouveau projet Docker** est créé
+- un projet est **installé pour la première fois sur le NUC**
+- un environnement doit être **reproduit sur une nouvelle machine**

60_playbooks/migration_projet_vers_nuc.md

@@ -0,0 +1,159 @@
+# 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 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 :
+
+```yaml
+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

60_playbooks/restaurer_backup_projet.md

@@ -0,0 +1,201 @@
+# Playbook — Restaurer un projet depuis un backup
+
+Ce playbook décrit la procédure standard pour **restaurer un projet Docker sur le NUC** à partir d’une sauvegarde.
+
+Il couvre principalement :
+
+- restauration de base de données
+- restauration de volumes persistants
+- redémarrage de la stack Docker
+
+Ce playbook est utilisé après :
+
+- une migration
+- une perte de données
+- la recréation d’un environnement
+
+---
+
+# Architecture de référence
+
+Sur le NUC, les données vivent dans :
+
+```
+/srv/
+  projects/        # code source
+  docker-data/     # volumes persistants
+  backups/         # sauvegardes
+```
+
+Les backups sont stockés dans :
+
+```
+/srv/backups/
+```
+
+Exemple :
+
+```
+/srv/backups/portfolio/
+```
+
+---
+
+# Étape 1 — Vérifier que le projet existe
+
+Le projet doit être présent dans :
+
+```
+/srv/projects/<nom-projet>
+```
+
+Sinon :
+
+```
+cd /srv/projects
+git clone <repo>
+```
+
+---
+
+# Étape 2 — Arrêter la stack
+
+Avant toute restauration, arrêter les conteneurs :
+
+```
+cd /srv/projects/<nom-projet>
+docker compose down
+```
+
+Cela évite les corruptions de données.
+
+---
+
+# Étape 3 — Restaurer les volumes persistants
+
+Si le backup contient des volumes :
+
+Exemple :
+
+```
+/srv/backups/portfolio/uploads
+/srv/backups/portfolio/postgres
+```
+
+Restaurer dans :
+
+```
+/srv/docker-data/<nom-projet>/
+```
+
+Exemple :
+
+```
+cp -r /srv/backups/portfolio/uploads /srv/docker-data/portfolio/
+```
+
+Important :
+
+- vérifier les permissions
+- vérifier que les dossiers existent
+
+---
+
+# Étape 4 — Restaurer la base de données
+
+Si un dump SQL est disponible :
+
+Exemple :
+
+```
+/srv/backups/portfolio/db.sql
+```
+
+Importer :
+
+```
+psql -U <user> -d <database> -f db.sql
+```
+
+Exemple concret :
+
+```
+psql -U portfolio_user -d portfolio -f /srv/backups/portfolio/db.sql
+```
+
+---
+
+# Étape 5 — Vérifier la configuration Docker
+
+Contrôler :
+
+- chemins des volumes
+- variables d’environnement
+- ports
+
+Fichier principal :
+
+```
+docker-compose.yml
+```
+
+---
+
+# Étape 6 — Redémarrer le projet
+
+Depuis le dossier projet :
+
+```
+docker compose up -d
+```
+
+Vérifier :
+
+```
+docker ps
+```
+
+---
+
+# Étape 7 — Vérifications post-restauration
+
+Contrôler :
+
+- que l’application démarre
+- que la base contient bien les données
+- que les volumes sont montés
+
+Commandes utiles :
+
+```
+docker compose logs -f
+```
+
+ou
+
+```
+docker logs <container>
+```
+
+---
+
+# Bonnes pratiques
+
+- toujours arrêter la stack avant restauration
+- restaurer les volumes **avant** de relancer Docker
+- vérifier les permissions des dossiers
+
+---
+
+# Quand utiliser ce playbook
+
+Utiliser ce playbook lorsque :
+
+- un projet doit être restauré après incident
+- un environnement doit être reconstruit
+- une sauvegarde doit être testée
+
+Ce playbook complète :
+
+- `bootstrap_projet_docker.md`
+- `migration_projet_vers_nuc.md`