homelab_automation/documentation/DOCKER_MANAGEMENT.md

# 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