# AGENTS.md - Instructions pour Mistral Vibe et autres agents

## 🎯 Workflow DevOps Homelab

### ✅ RÈGLES FONDAMENTALES

1. **TOUJOURS travailler depuis le dépôt Git**
   - Dépôt principal : https://git.peis.fr/VisualPCI/homelab-config
   - Clone local : `~/homelab-config` (WSL)
   - **JAMAIS** modifier les fichiers locaux sur `C:\Users\theo\.vibe\Proxmox\inventair\`

2. **Avant TOUTE action** :
   ```bash
   cd ~/homelab-config
   GIT_SSL_NO_VERIFY=true git pull origin main
   ```

3. **Après TOUTE modification** :
   ```bash
   git add .
   git commit -m "description claire de la modification"
   GIT_SSL_NO_VERIFY=true git push origin main
   ```

4. **Authentification Git** :
   - URL : `https://Windsurf:3N14E7GWVSgi3K@git.peis.fr/VisualPCI/homelab-config.git`
   - Utilisateur : Windsurf
   - Mot de passe / token : 3N14E7GWVSgi3K
   - Commit author : `Windsurf <windsurf@peis.fr>`

---

## 📁 Structure du dépôt

```
homelab-config/
├── AGENTS.md                  ← Ce fichier
├── INSTRUCTIONS.md           ← Instructions générales
├── homelab-inventaire.md     ← Inventaire principal
├── status-monitor/           ← Service de monitoring
│   ├── app.py                ← Code principal (corrigé)
│   ├── app_v1.py             ← Backup ancienne version
│   ├── app_v2.py             ← Backup ancienne version
│   ├── deploy.sh             ← Script de déploiement
│   └── dynamic_traefik.yml   ← Configuration Traefik
├── traefik-config/           ← Configurations Traefik
├── projet-authent/           ← Déploiement Authentik (CT203)
│   ├── docker-compose.yml    ← Stack Authentik
│   ├── .env                  ← Variables d'environnement
│   ├── authentik-secrets.md  ← Secrets
│   └── readme.md             ← Résumé du déploiement
└── procedure-*.md            ← Documentations
```

---

## 🚀 Déploiement Status Monitor (CT201)

### Serveur cible
- **IP** : 192.168.0.201
- **Service** : `status-monitor` (systemd)
- **Dossier** : `/opt/status-monitor/`
- **URL** : https://status.peis.fr

### Workflow de déploiement

**⚠️ Flux obligatoire : IDE (Windows) -> WSL -> CT200/CT100 (bastion 192.168.0.100) -> CT201 (192.168.0.201)**

```
IDE (C:\Users\theo\homelab_ia\homelab-config)
   └── copy ───> WSL (~/homelab-config)
                       └── scp -J root@192.168.0.100 ───> CT201 (192.168.0.201)
```

#### 1. Modifier le code dans l'IDE
Modifier `status-monitor/app.py` dans l'IDE Windows.

#### 2. Synchroniser IDE -> WSL
```bash
cp /mnt/c/Users/theo/homelab_ia/homelab-config/status-monitor/app.py ~/homelab-config/status-monitor/app.py
```

#### 3. Commiter et pusher
```bash
cd ~/homelab-config
GIT_SSL_NO_VERIFY=true git add status-monitor/
GIT_SSL_NO_VERIFY=true git commit -m "Fix: description de la correction"
GIT_SSL_NO_VERIFY=true git push origin main
```

#### 4. Déployer sur CT201
**Option A - Déploiement automatique (recommandé) :**
```bash
wsl bash ~/homelab-config/status-monitor/deploy.sh
```
Ce script synchronise automatiquement l'IDE -> WSL puis déploie via CT200/CT100.

**Option B - Déploiement manuel :**
```bash
# WSL -> CT201 (rebond via CT200/CT100 bastion)
scp -J root@192.168.0.100 -i ~/.ssh/id_ed25519 ~/homelab-config/status-monitor/app.py root@192.168.0.201:/tmp/app.py

# Installation et redémarrage sur CT201
ssh -J root@192.168.0.100 -i ~/.ssh/id_ed25519 root@192.168.0.201 'mv /tmp/app.py /opt/status-monitor/app.py && systemctl restart status-monitor'
```

#### 5. Vérifier le déploiement
```bash
# Vérifier l'API
curl -k -s https://status.peis.fr/api/status | python3 -m json.tool

# Ou via navigateur
https://status.peis.fr
```

---

## 🐞 Corrections courantes

### Problème : Cache non rafraîchi
**Symptôme** : La page status affiche des données anciennes

**Cause** : `status_cache` n'était pas rafraîchi après le premier chargement

**Solution appliquée** :
```python
# AVANT (bug) :
if not status_cache:
    check_all()

# APRÈS (corrigé) :
check_all()  # Toujours rafraîchir à chaque appel
```

**Fichier** : `status-monitor/app.py` (ligne 372)

---

## 📋 Commandes utiles

### Git
```bash
# État
cd ~/homelab-config && git status

# Pull
cd ~/homelab-config && git pull

# Commit
cd ~/homelab-config && git add . && git commit -m "message" && git push

# Voir l'historique
cd ~/homelab-config && git log --oneline --graph
```

### SSH CT201 (via rebond CT200)
```bash
# Se connecter (CT200 est le bastion)
ssh -J root@192.168.0.100 root@192.168.0.201

# Voir les logs du service
ssh -J root@192.168.0.100 root@192.168.0.201 "journalctl -u status-monitor -f"

# État du service
ssh -J root@192.168.0.100 root@192.168.0.201 "systemctl status status-monitor"

# Redémarrer
ssh -J root@192.168.0.100 root@192.168.0.201 "systemctl restart status-monitor"
```

### SSH CT200 (direct)
```bash
# Se connecter directement
ssh -i ~/.ssh/id_ed25519 root@192.168.0.100

# Copier des fichiers vers CT200
scp -i ~/.ssh/id_ed25519 fichier root@192.168.0.100:/destination/

# Copier des fichiers de CT200 vers local
scp -i ~/.ssh/id_ed25519 root@192.168.0.100:/source/fichier ./
```

### Gitea
- **URL** : https://git.peis.fr
- **Compte** : VisualPCI
- **Dépôt** : https://git.peis.fr/VisualPCI/homelab-config

### Workflow complet utilisé pour la correction du 20/07/2026

**Problème** : SyntaxError: Unexpected identifier 'card' (at index.html:101:35)
**Cause** : Dans `status-monitor/app.py`, les strings JavaScript utilisaient `class=\"` qui générait du code JS invalide.

**Workflow appliqué** :
```bash
# 1. Cloner depuis WSL (Ubuntu)
cd ~/homelab-config
git clone https://VisualPCI:3N14E7GWVSgi3K@git.peis.fr/VisualPCI/homelab-config.git

# 2. Récupérer le fichier buggé depuis CT201 (via CT200)
ssh -J root@192.168.0.100 root@192.168.0.201 cat /opt/status-monitor/app.py > status-monitor/app_from_ct201.py

# 3. Corriger le bug avec Python (remplacer \" par ')
python3 -c "
with open('status-monitor/app.py', 'r') as f:
    content = f.read()
content = content.replace('\\\"', \"'\")
with open('status-monitor/app.py', 'w') as f:
    f.write(content)
"

# 4. Vérifier la syntaxe Python
python3 -m py_compile status-monitor/app.py

# 5. Commiter avec GIT_SSL_NO_VERIFY
GIT_SSL_NO_VERIFY=true git add status-monitor/app.py
GIT_SSL_NO_VERIFY=true git commit -m "Fix(status-monitor): Correction des guillemets dans le JavaScript - Resout SyntaxError loading"

# 6. Pull avec rebase (conflit détecté)
GIT_SSL_NO_VERIFY=true git pull --rebase origin main

# 7. Pousser vers git.peis.fr
GIT_SSL_NO_VERIFY=true git push origin main

# 8. Deployer sur CT201 (via CT200 comme bastion)
# Méthode 1 : Copier via CT200
cat status-monitor/app.py | ssh -i ~/.ssh/id_ed25519 root@192.168.0.100 'cat > /tmp/app_new.py'
ssh -i ~/.ssh/id_ed25519 root@192.168.0.100 'scp /tmp/app_new.py root@192.168.0.201:/opt/status-monitor/app.py && chmod +x /opt/status-monitor/app.py'
ssh -i ~/.ssh/id_ed25519 root@192.168.0.100 'ssh root@192.168.0.201 systemctl restart status-monitor'

# Méthode 2 : Direct avec -J (bastion)
scp -J root@192.168.0.100 -i ~/.ssh/id_ed25519 status-monitor/app.py root@192.168.0.201:/opt/status-monitor/app.py
ssh -J root@192.168.0.100 root@192.168.0.201 'chmod +x /opt/status-monitor/app.py && systemctl restart status-monitor'
```

**Résultat** :
- Commit `685060c` poussé vers git.peis.fr
- Fichier corrigé déployé sur CT201
- Service redémarré avec succès

**Leçons apprises** :
- Toujours utiliser `-J` pour le rebond SSH vers CT201
- `GIT_SSL_NO_VERIFY=true` est nécessaire pour contourner les problèmes de certificat
- Utiliser `python3` pour les scripts de correction complexes
- Tester la syntaxe Python avant de deployer

---

## 🚨 Erreurs à éviter

- ❌ Modifier directement les fichiers sur CT201 sans passer par Git
- ❌ Oublier de faire `git pull` avant de modifier un fichier
- ❌ Oublier de commiter et pusher après une modification
- ❌ Travailler depuis plusieurs emplacements différents
- ❌ Modifier les fichiers dans `C:\Users\theo\.vibe\Proxmox\inventair\`

---

## ✅ Checklist avant déploiement

- [ ] `git pull` exécuté
- [ ] Modifications testées localement
- [ ] `git add .` exécuté
- [ ] `git commit -m "..."` exécuté
- [ ] `git push origin main` exécuté
- [ ] Déploiement vérifié sur https://status.peis.fr

---

## 📊 Historique des modifications

| Date | Commit | Description |
|------|--------|-------------|
| 2026-07-20 | `685060c` | Fix(status-monitor): Correction des guillemets dans le JavaScript - Resout SyntaxError loading |
| 2026-07-19 | `6b77f49` | Fix: Force cache refresh on /api/status endpoint |
| 2026-07-19 | `3ed1d96` | Add: deploy.sh script for DevOps workflow |
| 2026-07-19 | `da6b794` | Ajout: INSTRUCTIONS.md pour workflow Git |

---

*Dernière mise à jour : 2026-07-20*

*Dernière mise à jour : 2026-07-19*
*Pour : Mistral Vibe et agents homelab*