zebra-power/README.md

# Zebra Power 🍅

Application web dockerisée pour la gestion unifiée d'hosts Proxmox avec Wake-on-LAN, contrôle de VMs/Containers et extinction complète.

## Architecture

### Modèle unifié ProxmoxHost
- **Wake-on-LAN** : Démarrage via IP/MAC
- **Proxmox** : Gestion VMs/Containers  
- **Shutdown** : Extinction host complet
- **Une seule configuration** par host physique

### Stack technique
- **Backend** : Python 3.13 + FastAPI 0.115.0 + SQLAlchemy 2.0.35 + uv
- **Frontend** : Vue.js 3.4.0 + Vite 5.0.8 + Tailwind CSS 3.3.6
- **Base de données** : SQLite
- **Infrastructure** : Docker Compose + Nginx 1.25

## Installation et lancement

### Développement (avec hot reload)
```bash
# Lancer l'application en mode développement
docker-compose -f docker-compose.dev.yml up -d

# Voir les logs
docker-compose -f docker-compose.dev.yml logs -f

# Arrêter
docker-compose -f docker-compose.dev.yml down
```

**Accès développement :**
- Frontend : http://localhost:3000
- Backend API : http://localhost:8000  
- Documentation API : http://localhost:8000/docs

### Production
```bash
# Lancer l'application en production
docker-compose up -d

# Voir les logs
docker-compose logs -f

# Arrêter
docker-compose down
```

**Accès production :**
- Application complète : http://localhost

## Interface utilisateur

### Page Hosts unifiée (`/hosts`)
**Workflow intégré par host :**
1. ⚡ **Wake** - Démarrage WOL
2. 🔄 **VMs** - Chargement et contrôle VMs/Containers  
3. 🛑 **Shutdown** - Extinction host et toutes VMs

**Fonctionnalités :**
- Statut temps réel (en ligne/hors ligne)
- Configuration complète (WOL + Proxmox)
- Actions groupées par host physique

### Dashboard (`/`)
**Vue d'ensemble :**
- Nombre total d'hosts et statut
- VMs/Containers actives
- Actions rapides Wake/Start/Stop
- Logs récents centralisés

## API

### Endpoints principaux
- `GET /api/hosts` - Liste des hosts
- `POST /api/hosts` - Créer un host  
- `POST /api/hosts/{id}/wake` - Wake-on-LAN
- `GET /api/hosts/{id}/vms` - VMs du host
- `POST /api/hosts/{id}/vms/{vmid}/start` - Démarrer VM
- `POST /api/hosts/{id}/vms/{vmid}/stop` - Arrêter VM
- `POST /api/hosts/{id}/shutdown` - Éteindre host
- `GET /api/wol/all-logs` - Logs centralisés

### Structure ProxmoxHost
```json
{
  "name": "Mon Host",
  "description": "Description optionnelle",
  "ip_address": "192.168.1.100",
  "mac_address": "00:11:22:33:44:55",
  "proxmox_host": "192.168.1.100",
  "proxmox_username": "root",
  "proxmox_password": "password",
  "proxmox_port": 8006,
  "verify_ssl": false,
  "shutdown_endpoint": "/api/shutdown"
}
```

## Migration depuis ancienne architecture

### Migration des données
```bash
# Migrer serveurs et clusters vers hosts unifiés
docker exec -it zebra_backend uv run python migrate_to_unified_hosts.py

# Optionnel : nettoyer anciennes tables après validation
docker exec -it zebra_backend uv run python cleanup_old_tables.py
```

### Redirections automatiques
- `/servers` → `/hosts`  
- `/proxmox` → `/hosts`

## Base de données

### Table principale
- **`proxmox_hosts`** - Configuration unifiée hosts
- **`action_logs`** - Historique centralisé toutes actions
- **`wol_logs`** - Legacy (rétrocompatibilité)

### Sauvegarde
```bash
# Sauvegarder la base
cp ./data/zebra.db ./data/zebra.db.backup

# Restaurer
cp ./data/zebra.db.backup ./data/zebra.db
```

## Développement

### Structure backend
```
backend/app/
├── api/hosts.py          # API unifiée hosts
├── api/wol.py           # Logs (legacy)
├── models/schemas.py    # ProxmoxHost schemas
├── services/
│   ├── proxmox_host_service.py  # Service unifié
│   ├── logging_service.py       # Logs centralisés
│   └── wol_service.py          # Utilitaires WOL
├── database.py          # Modèles SQLAlchemy
└── main.py             # Application FastAPI
```

### Structure frontend
```
frontend/src/
├── views/
│   ├── Hosts.vue       # Interface unifiée
│   └── Dashboard.vue   # Vue d'ensemble
├── services/api.js     # hostsApi, logsApi
└── main.js            # Routes et configuration
```

### Commandes utiles
```bash
# Tests backend
docker exec -it zebra_backend uv run python test_api.py

# Build images
docker-compose build --no-cache

# Logs spécifiques
docker-compose logs backend
docker-compose logs frontend
docker-compose logs nginx

# Health checks
docker inspect --format='{{.State.Health.Status}}' zebra_backend
```

## Sécurité

- Mode host requis pour Wake-on-LAN
- Validation Pydantic des entrées API
- Logging centralisé de toutes actions
- Gestion des erreurs et timeouts
- Health checks Docker intégrés

## Réseau

### Ports
- **80** : Nginx (production)
- **3000** : Frontend (développement)  
- **8000** : Backend API (développement)

### Exigences WOL
- Backend en `network_mode: host`
- Paquet `wakeonlan` installé  
- Accès réseau local pour broadcast

L'application est maintenant entièrement unifiée avec une architecture simplifiée et moderne.