Remove Node.js cache files containing npm vulnerability data for vitest and vite packages

2025-12-15 20:36:06 -05:00
parent 27eed55c9b
commit 68a9b0f390
123 changed files with 13216 additions and 157 deletions
@@ -0,0 +1,336 @@
+# Docker Management - Documentation
+
+## Vue d'ensemble
+
+La fonctionnalité de gestion Docker permet de surveiller et gérer les containers Docker sur plusieurs hosts de votre homelab. Elle s'intègre harmonieusement avec l'architecture existante du Homelab Dashboard.
+
+## Fonctionnalités
+
+### Surveillance multi-hosts
+- Collecte automatique des informations Docker via SSH
+- Vue d'ensemble de tous les hosts Docker-enabled
+- Statistiques globales (containers, images, volumes, alertes)
+
+### Gestion des containers
+- **Start/Stop/Restart** : Actions de base sur les containers
+- **Logs** : Visualisation des logs en temps réel
+- **Inspect** : Informations détaillées JSON
+- **Redeploy** : Pull de l'image et recréation (support docker-compose)
+
+### Alerting proactif
+- Détection automatique des containers down
+- Notifications ntfy lors d'alertes
+- Système d'acquittement des alertes
+- Labels pour configurer la surveillance
+
+## Architecture
+
+### Backend
+
+```
+app/
+├── models/
+│   ├── docker_container.py    # Modèle SQLAlchemy containers
+│   ├── docker_image.py        # Modèle SQLAlchemy images
+│   ├── docker_volume.py       # Modèle SQLAlchemy volumes
+│   └── docker_alert.py        # Modèle SQLAlchemy alertes
+├── crud/
+│   ├── docker_container.py    # CRUD operations containers
+│   ├── docker_image.py        # CRUD operations images
+│   ├── docker_volume.py       # CRUD operations volumes
+│   └── docker_alert.py        # CRUD operations alertes
+├── schemas/
+│   └── docker.py              # Schémas Pydantic
+├── services/
+│   ├── docker_service.py      # Service de collecte SSH
+│   ├── docker_actions.py      # Actions sur containers
+│   └── docker_alerts.py       # Gestion des alertes
+└── routes/
+    └── docker.py              # API endpoints
+```
+
+### Frontend
+
+```
+app/
+├── index.html                 # Section Docker (page-docker)
+└── docker_section.js          # Logique JavaScript
+```
+
+## API Endpoints
+
+### Hosts Docker
+
+| Endpoint | Méthode | Description |
+|----------|---------|-------------|
+| `/api/docker/hosts` | GET | Liste tous les hosts avec infos Docker |
+| `/api/docker/hosts/{host_id}/enable` | POST | Active/désactive surveillance Docker |
+| `/api/docker/hosts/{host_id}/collect` | POST | Force une collecte immédiate |
+| `/api/docker/collect-all` | POST | Collecte sur tous les hosts enabled |
+
+### Containers
+
+| Endpoint | Méthode | Description |
+|----------|---------|-------------|
+| `/api/docker/hosts/{host_id}/containers` | GET | Liste containers d'un host |
+| `/api/docker/containers/{host_id}/{container_id}/start` | POST | Démarre un container |
+| `/api/docker/containers/{host_id}/{container_id}/stop` | POST | Arrête un container |
+| `/api/docker/containers/{host_id}/{container_id}/restart` | POST | Redémarre un container |
+| `/api/docker/containers/{host_id}/{container_id}/remove` | POST | Supprime un container (admin) |
+| `/api/docker/containers/{host_id}/{container_id}/redeploy` | POST | Redéploie un container |
+| `/api/docker/containers/{host_id}/{container_id}/logs` | GET | Récupère les logs |
+| `/api/docker/containers/{host_id}/{container_id}/inspect` | GET | Informations détaillées |
+
+### Images & Volumes
+
+| Endpoint | Méthode | Description |
+|----------|---------|-------------|
+| `/api/docker/hosts/{host_id}/images` | GET | Liste images d'un host |
+| `/api/docker/hosts/{host_id}/volumes` | GET | Liste volumes d'un host |
+
+### Alertes
+
+| Endpoint | Méthode | Description |
+|----------|---------|-------------|
+| `/api/docker/alerts` | GET | Liste les alertes Docker |
+| `/api/docker/alerts/{alert_id}/acknowledge` | POST | Acquitte une alerte |
+| `/api/docker/alerts/{alert_id}/close` | POST | Ferme une alerte |
+
+### Statistiques
+
+| Endpoint | Méthode | Description |
+|----------|---------|-------------|
+| `/api/docker/stats` | GET | Statistiques globales Docker |
+
+## Configuration
+
+### Activer Docker sur un host
+
+1. **Via l'API** :
+```bash
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  http://localhost:8000/api/docker/hosts/{host_id}/enable \
+  -H "Content-Type: application/json" \
+  -d '{"enabled": true}'
+```
+
+2. **Via l'interface** : Section Docker > Cliquez sur le bouton play/pause sur un host
+
+### Labelliser les containers pour l'alerting
+
+Ajoutez ces labels à vos containers pour activer la surveillance :
+
+```yaml
+# docker-compose.yml
+services:
+  nginx:
+    image: nginx:latest
+    labels:
+      homelab.monitor: "true"      # Active la surveillance
+      homelab.desired: "running"   # État attendu (running/stopped)
+```
+
+Les containers avec `homelab.monitor: "true"` seront surveillés. Si leur état ne correspond pas à `homelab.desired`, une alerte sera créée.
+
+### Jobs planifiés
+
+Deux jobs APScheduler sont configurés automatiquement au démarrage :
+
+1. **docker_collect** (toutes les 60 secondes) : Collecte les infos Docker de tous les hosts enabled
+2. **docker_alerts** (toutes les 30 secondes) : Vérifie l'état des containers et génère des alertes
+
+## Collecte via SSH
+
+La collecte Docker utilise SSH pour exécuter des commandes Docker sur les hosts distants. Le système réutilise la configuration SSH existante (user `automation`, clés SSH).
+
+### Commandes exécutées
+
+```bash
+# Version Docker
+docker version --format '{{.Server.Version}}'
+
+# Containers
+docker ps -a --format '{{json .}}' --no-trunc
+
+# Images
+docker images --format '{{json .}}'
+
+# Volumes
+docker volume ls --format '{{json .}}'
+```
+
+### Timeouts
+
+- **Connect timeout** : 5 secondes
+- **Exec timeout** : 15 secondes (30 secondes pour les actions)
+
+## Base de données
+
+### Migration Alembic
+
+```bash
+# Appliquer la migration
+alembic upgrade head
+```
+
+La migration `0011_add_docker_management_tables.py` crée :
+- Extension de la table `hosts` avec colonnes Docker
+- Table `docker_containers`
+- Table `docker_images`
+- Table `docker_volumes`
+- Table `docker_alerts`
+
+### Schéma des tables
+
+```sql
+-- Extension hosts
+ALTER TABLE hosts ADD COLUMN docker_enabled BOOLEAN DEFAULT FALSE;
+ALTER TABLE hosts ADD COLUMN docker_version TEXT;
+ALTER TABLE hosts ADD COLUMN docker_status TEXT;  -- online/offline/error
+ALTER TABLE hosts ADD COLUMN docker_last_collect_at TIMESTAMP;
+
+-- Containers
+CREATE TABLE docker_containers (
+    id INTEGER PRIMARY KEY,
+    host_id TEXT REFERENCES hosts(id) ON DELETE CASCADE,
+    container_id TEXT NOT NULL,
+    name TEXT NOT NULL,
+    image TEXT,
+    state TEXT,           -- running/exited/paused/created/dead
+    status TEXT,          -- "Up 2 hours", etc.
+    health TEXT,          -- healthy/unhealthy/starting/none
+    created_at TIMESTAMP,
+    ports JSON,
+    labels JSON,
+    compose_project TEXT, -- com.docker.compose.project
+    last_update_at TIMESTAMP
+);
+
+-- Alertes
+CREATE TABLE docker_alerts (
+    id INTEGER PRIMARY KEY,
+    host_id TEXT REFERENCES hosts(id) ON DELETE CASCADE,
+    container_name TEXT NOT NULL,
+    severity TEXT,        -- warning/error/critical
+    state TEXT,           -- open/closed/acknowledged
+    message TEXT,
+    opened_at TIMESTAMP,
+    closed_at TIMESTAMP,
+    acknowledged_at TIMESTAMP,
+    acknowledged_by TEXT,
+    last_notified_at TIMESTAMP
+);
+```
+
+## Interface utilisateur
+
+### Section Docker
+
+- **Statistiques** : Cards avec nombre de hosts, containers, images, alertes
+- **Actions** : Bouton "Collecter Tout", accès aux alertes Docker
+- **Recherche** : Filtre les hosts par nom ou IP
+- **Grille hosts** : Cards cliquables pour chaque host Docker
+
+### Modal détails host
+
+Onglets disponibles :
+- **Containers** : Liste avec actions (start/stop/restart/logs)
+- **Images** : Liste des images avec taille
+- **Volumes** : Liste des volumes
+- **Alertes** : Alertes spécifiques à ce host
+
+### Notifications temps réel
+
+Via WebSocket, le frontend reçoit :
+- `docker_host_updated` : Mise à jour d'un host
+- `docker_alert_opened` : Nouvelle alerte
+- `docker_alert_closed` : Alerte fermée
+- `docker_alert_acknowledged` : Alerte acquittée
+
+## Sécurité
+
+- Toutes les routes nécessitent une authentification (JWT ou API Key)
+- L'action `remove` nécessite le rôle `admin`
+- Timeouts stricts pour éviter les blocages SSH
+- Pas d'exécution de commandes arbitraires
+
+## Exemples curl
+
+### Lister les hosts Docker
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  http://localhost:8000/api/docker/hosts
+```
+
+### Activer Docker sur un host
+```bash
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  http://localhost:8000/api/docker/hosts/host-123/enable \
+  -H "Content-Type: application/json" \
+  -d '{"enabled": true}'
+```
+
+### Forcer une collecte
+```bash
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  http://localhost:8000/api/docker/hosts/host-123/collect
+```
+
+### Démarrer un container
+```bash
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  http://localhost:8000/api/docker/containers/host-123/abc456def/start
+```
+
+### Voir les logs d'un container
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:8000/api/docker/containers/host-123/abc456def/logs?tail=200"
+```
+
+### Lister les alertes ouvertes
+```bash
+curl -H "Authorization: Bearer $TOKEN" \
+  "http://localhost:8000/api/docker/alerts?state=open"
+```
+
+### Acquitter une alerte
+```bash
+curl -X POST -H "Authorization: Bearer $TOKEN" \
+  http://localhost:8000/api/docker/alerts/1/acknowledge \
+  -H "Content-Type: application/json" \
+  -d '{"note": "Investigating the issue"}'
+```
+
+## Dépendances
+
+### Python
+- `asyncssh` : Connexions SSH asynchrones
+- Dépendances existantes (FastAPI, SQLAlchemy, APScheduler, etc.)
+
+### Ajout de asyncssh
+Si asyncssh n'est pas installé :
+```bash
+pip install asyncssh
+```
+
+## Dépannage
+
+### Erreur "Docker not available"
+- Vérifier que Docker est installé sur le host
+- Vérifier que l'utilisateur `automation` a les droits Docker (`docker` group)
+
+### Timeouts SSH
+- Vérifier la connectivité réseau
+- Vérifier les clés SSH
+- Augmenter les timeouts si nécessaire dans `docker_service.py`
+
+### Containers non détectés
+- Vérifier que Docker monitoring est activé sur le host
+- Forcer une collecte manuelle
+- Vérifier les logs de l'application
+
+### Alertes non envoyées
+- Vérifier que ntfy est configuré et activé
+- Vérifier les labels `homelab.monitor` sur les containers
+- Vérifier les logs pour les erreurs de notification