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 :

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 :

# 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

# 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

# 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

-- 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

curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/docker/hosts

Activer Docker sur un host

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

curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/docker/hosts/host-123/collect

Démarrer un container

curl -X POST -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/docker/containers/host-123/abc456def/start

Voir les logs d'un container

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/docker/containers/host-123/abc456def/logs?tail=200"

Lister les alertes ouvertes

curl -H "Authorization: Bearer $TOKEN" \
  "http://localhost:8000/api/docker/alerts?state=open"

Acquitter une alerte

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é :

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