zebra-power/DOCUMENTATION.md

Documentation Technique - Zebra Power 🍅

Vue d'ensemble

Zebra Power (nommée d'après la tomate verte zebra) est une application web dockerisée développée pour la gestion centralisée de serveurs via Wake-on-LAN et le contrôle de machines virtuelles Proxmox. L'application suit une architecture moderne avec séparation frontend/backend et utilise des standards industriels.

Architecture Système

Structure Générale

zebra_power/
├── backend/          # API FastAPI
├── frontend/         # Interface Vue.js 3
├── nginx/           # Proxy reverse
├── data/            # Persistance SQLite
└── docker-compose.yml

Technologies

Backend (Python)

• Framework: FastAPI 0.104.1 - API REST haute performance
• Base de données: SQLAlchemy 2.0.23 avec SQLite
• Validation: Pydantic 2.5.0 pour la sérialisation/validation des données
• Serveur: Uvicorn avec support asynchrone
• Intégrations:
  • proxmoxer 2.0.1 pour l'API Proxmox
  • wakeonlan 3.1.0 pour les paquets magiques WOL
  • httpx 0.25.2 pour les requêtes HTTP asynchrones

Frontend (JavaScript/Vue.js)

• Framework: Vue.js 3.4.0 avec Composition API
• Routing: Vue Router 4.2.5
• State Management: Pinia 2.1.7
• HTTP Client: Axios 1.6.2
• UI Components:
  • Headless UI Vue 1.7.16
  • Heroicons Vue 2.0.18
• Styling: Tailwind CSS 3.3.6
• Build Tool: Vite 5.0.8

Infrastructure

• Containerisation: Docker avec Docker Compose
• Proxy: Nginx pour le routage et les fichiers statiques
• Réseau: Mode host pour le backend (requis pour WOL)

Modèles de Données

Serveurs (servers)

class Server:
    id: int                    # Clé primaire
    name: str                  # Nom du serveur
    ip_address: str           # Adresse IP
    mac_address: str          # Adresse MAC pour WOL
    description: str?         # Description optionnelle
    is_online: bool          # État en ligne (ping)
    last_ping: datetime?     # Dernier ping réussi
    created_at: datetime     # Date de création

Clusters Proxmox (proxmox_clusters)

class ProxmoxCluster:
    id: int                  # Clé primaire
    name: str               # Nom du cluster
    host: str               # IP/hostname Proxmox
    username: str           # Utilisateur (ex: root@pam)
    password: str           # Mot de passe
    port: int = 8006       # Port API Proxmox
    verify_ssl: bool       # Vérification SSL
    created_at: datetime   # Date de création

Journalisation (action_logs)

class ActionLog:
    id: int                    # Clé primaire
    action_type: str          # Type: 'wol', 'proxmox', 'server'
    target_id: int?          # ID de la cible
    target_name: str?        # Nom de la cible
    action: str              # Action: 'wake', 'start', 'stop', etc.
    timestamp: datetime      # Horodatage
    success: bool           # Succès/échec
    message: str?           # Message descriptif
    details: str?           # Données JSON supplémentaires

Architecture API

Endpoints Serveurs (/api/servers)

• GET / - Liste tous les serveurs avec statut
• POST / - Créer un nouveau serveur
• PUT /{id} - Modifier un serveur existant
• DELETE /{id} - Supprimer un serveur

Endpoints Wake-on-LAN (/api/wol)

• POST /wake/{server_id} - Envoyer paquet magique WOL
• POST /ping/{server_id} - Tester la connectivité
• GET /logs - Récupérer l'historique WOL

Endpoints Proxmox (/api/proxmox)

• GET /clusters - Liste des clusters configurés
• POST /clusters - Ajouter un nouveau cluster
• PUT /clusters/{id} - Modifier un cluster
• DELETE /clusters/{id} - Supprimer un cluster
• GET /clusters/{id}/vms - Liste des VMs/containers
• POST /clusters/{id}/vms/{vmid}/start - Démarrer VM/container
• POST /clusters/{id}/vms/{vmid}/stop - Arrêter VM/container
• POST /clusters/{id}/vms/{vmid}/restart - Redémarrer VM/container

Services Backend

Services de Base (app/services/)

WoL Service (wol_service.py)

• Envoi de paquets magiques Wake-on-LAN
• Ping automatique pour vérification de statut
• Logging des actions WOL
• Validation des adresses MAC

Proxmox Service (proxmox_service.py)

• Connexion sécurisée aux clusters Proxmox
• Gestion de l'authentification
• Récupération des états VMs/containers
• Contrôle des machines virtuelles

Logging Service (logging_service.py)

• Centralisation des logs d'actions
• Structuration des événements
• Persistance en base de données
• Historique des opérations

Architecture Frontend

Structure Vue.js (frontend/src/)

Composants Principaux

• App.vue - Composant racine avec navigation
• views/Dashboard.vue - Tableau de bord général
• views/Servers.vue - Gestion des serveurs WOL
• views/Proxmox.vue - Interface Proxmox

Services

• services/api.js - Client HTTP centralisé pour l'API

Routing

Configuration Vue Router pour navigation SPA avec lazy loading

State Management

Pinia stores pour:

• État des serveurs
• Configuration Proxmox
• Logs et historique

Configuration Réseau

Ports et Services

• 80 - Nginx (point d'entrée principal)
• 3000 - Frontend Vue.js (développement)
• 8000 - Backend FastAPI
• 8006 - API Proxmox (configurable)

Réseau Docker

• Backend en mode host pour envoi de paquets WOL
• Frontend et Nginx en réseau bridge standard
• Communication inter-conteneurs via noms de services

Sécurité

Authentification Proxmox

• Stockage chiffré des mots de passe (à améliorer)
• Support de l'authentification PAM/PVE
• Gestion des certificats SSL

CORS et Sécurité API

• Configuration CORS permissive (à restreindre en production)
• Gestion globale des exceptions
• Validation Pydantic des entrées

Recommandations

1. Implémenter un système d'authentification pour l'interface
2. Chiffrer les mots de passe Proxmox en base
3. Restreindre les origines CORS
4. Ajouter HTTPS avec certificats SSL

Monitoring et Logs

Logging Structure

• Logs d'actions centralisés
• Horodatage UTC
• Détails JSON pour traçabilité
• Séparation par type d'action

Monitoring Serveurs

• Ping automatique périodique
• Mise à jour statut en temps réel
• Historique de disponibilité

Déploiement et Maintenance

Environnement de Développement

# Backend
cd backend && pip install -r requirements.txt
uvicorn app.main:app --reload

# Frontend  
cd frontend && npm install && npm run dev

Production Docker

docker-compose up -d

Sauvegarde

• Base de données: ./data/zebra.db
• Configuration: Variables d'environnement Docker
• Logs: Intégrés à la base SQLite

Performance et Optimisations

Base de Données

• SQLite pour simplicité (migration PostgreSQL recommandée)
• Index sur colonnes fréquemment requêtées
• Sessions SQLAlchemy avec pool de connexions

Frontend

• Lazy loading des composants Vue
• Build optimisé avec Vite
• CSS Tailwind avec purge automatique

Infrastructure

• Nginx pour fichiers statiques et cache
• Compression gzip activée
• Reverse proxy avec load balancing potentiel

Tests et Qualité

Recommandations de Tests

1. Tests unitaires backend avec pytest
2. Tests d'intégration API avec httpx
3. Tests frontend avec Vitest
4. Tests E2E avec Cypress

Métriques Qualité

• Couverture de code minimale 80%
• Linting ESLint/Pylint
• Formatage avec Prettier/Black
• Validation TypeScript progressive

Évolutions Futures

Fonctionnalités Planifiées

1. Authentification utilisateurs
2. Groupes et permissions
3. Monitoring avancé avec métriques
4. Notifications (email, webhook)
5. API GraphQL
6. Interface mobile responsive

Améliorations Techniques

1. Migration PostgreSQL
2. Microservices avec FastAPI
3. Cache Redis
4. Queue de tâches Celery
5. Observabilité (metrics, tracing)