innotexBoard/DOCKER_UPDATE_SYSTEM.md

Docker Image Update System - InnotexBoard

📌 Vue d'ensemble

Le système de mise à jour Docker d'InnotexBoard est inspiré de TrueNAS Scale et fournit:

• ✅ Vérification automatique des mises à jour d'images
• ✅ Téléchargement (pull) des nouvelles images
• ✅ Mise à jour in-place des conteneurs
• ✅ Nettoyage automatique des images orphelines
• ✅ Gestion centralisée des docker-compose

🏗️ Architecture

InnotexBoard
├── Backend API (FastAPI)
│   ├── update_service.py         # Service de mise à jour des images
│   ├── compose_manager.py        # Manager des docker-compose
│   ├── endpoints/docker.py       # API endpoints pour Docker
│   └── endpoints/compose.py      # API endpoints pour Docker Compose
│
├── Frontend (Vue.js)
│   └── Components
│       ├── ImageUpdates.vue      # Gestion des mises à jour
│       └── ComposeManager.vue    # Gestion des docker-compose
│
└── Docker References
    └── /home/innotex/Docker/
        ├── docker-compose.*.yml
        └── README.md

🔄 Workflow de Mise à Jour (Inspiré de TrueNAS Scale)

1. Détection des Mises à Jour

Client → GET /api/v1/docker/images/check-all-updates
        → Check Docker Registry V2 API
        → Compare versions (sémantique)
        → Return list of available updates

2. Téléchargement des Images

Client → POST /api/v1/docker/images/pull
        → docker pull {image}:{tag}
        → Store locally

3. Mise à Jour Atomique du Conteneur

Client → POST /api/v1/docker/containers/{id}/update-image
        ↓
        1. Stop container
        2. Pull new image
        3. Remove old container
        4. Create new container with new image
        5. Start new container
        ↓
        Rollback-safe (old image retained until prune)

4. Nettoyage

Client → POST /api/v1/docker/images/prune
        → Remove dangling images
        → Free up disk space

📡 API Endpoints

Images Management

Lister toutes les images locales

GET /api/v1/docker/images
Authorization: Bearer {token}

Response 200:
{
  "images": [
    {
      "image": "portainer/portainer-ce",
      "tag": "latest",
      "image_id": "abc123",
      "created": "2024-01-16T10:30:00Z",
      "size": "123.45 MB",
      "containers_using": ["portainer"]
    }
  ]
}

Vérifier les mises à jour d'une image

GET /api/v1/docker/images/check-update/{image_name}
Authorization: Bearer {token}

Response 200:
{
  "image": "portainer/portainer-ce:latest",
  "current_tag": "latest",
  "latest_tag": "2.19.3",
  "has_update": true,
  "registry": "docker.io"
}

Vérifier toutes les mises à jour

GET /api/v1/docker/images/check-all-updates
Authorization: Bearer {token}

Response 200:
{
  "total_containers": 5,
  "containers_with_updates": 2,
  "updates": [
    {
      "container": "portainer",
      "update": {
        "image": "portainer/portainer-ce:latest",
        "current_tag": "latest",
        "latest_tag": "2.19.3",
        "has_update": true,
        "registry": "docker.io"
      }
    }
  ]
}

Télécharger une image (Pull)

POST /api/v1/docker/images/pull
Authorization: Bearer {token}
Content-Type: application/json

Body:
{
  "image": "portainer/portainer-ce",
  "tag": "latest"
}

Response 200:
{
  "status": "success",
  "message": "Image portainer/portainer-ce:latest téléchargée avec succès"
}

Mettre à jour l'image d'un conteneur

POST /api/v1/docker/containers/{container_id}/update-image
Authorization: Bearer {token}
Content-Type: application/json

Body:
{
  "new_image": "portainer/portainer-ce",
  "new_tag": "latest"
}

Response 200:
{
  "success": true,
  "message": "Conteneur portainer mis à jour avec succès",
  "old_image": "portainer/portainer-ce:2.19.0",
  "new_image": "portainer/portainer-ce:latest"
}

Nettoyer les images inutilisées

POST /api/v1/docker/images/prune
Authorization: Bearer {token}

Query Parameters:
- dangling_only: boolean (default: true)

Response 200:
{
  "success": true,
  "deleted_images": 5,
  "space_freed_mb": "234.56",
  "details": [...]
}

Docker Compose Management

Lister tous les docker-compose disponibles

GET /api/v1/docker/compose/list
Authorization: Bearer {token}

Response 200:
[
  {
    "name": "portainer",
    "file": "docker-compose.portainer.yml",
    "path": "/home/innotex/Docker/docker-compose.portainer.yml",
    "exists": true
  },
  ...
]

Vérifier l'état d'un docker-compose

GET /api/v1/docker/compose/{compose_name}/status
Authorization: Bearer {token}

Response 200:
{
  "status": "success",
  "file": "docker-compose.portainer.yml",
  "containers": [
    {
      "ID": "abc123",
      "Name": "portainer",
      "State": "running",
      "Status": "Up 2 hours"
    }
  ],
  "count": 1
}

Démarrer un docker-compose

POST /api/v1/docker/compose/{compose_name}/start
Authorization: Bearer {token}

Response 200:
{
  "status": "success",
  "message": "Services démarrés pour docker-compose.portainer.yml"
}

Arrêter un docker-compose

POST /api/v1/docker/compose/{compose_name}/stop
Authorization: Bearer {token}

Response 200:
{
  "status": "success",
  "message": "Services arrêtés pour docker-compose.portainer.yml"
}

Arrêter et supprimer (down)

POST /api/v1/docker/compose/{compose_name}/down
Authorization: Bearer {token}

Response 200:
{
  "status": "success",
  "message": "Services arrêtés et supprimés pour docker-compose.portainer.yml"
}

Redémarrer un docker-compose

POST /api/v1/docker/compose/{compose_name}/restart
Authorization: Bearer {token}

Response 200:
{
  "status": "success",
  "message": "Services redémarrés pour docker-compose.portainer.yml"
}

Télécharger les images (Pull) d'un docker-compose

POST /api/v1/docker/compose/{compose_name}/pull
Authorization: Bearer {token}

Response 200:
{
  "status": "success",
  "message": "Images téléchargées pour docker-compose.portainer.yml"
}

Récupérer les logs

GET /api/v1/docker/compose/{compose_name}/logs
Authorization: Bearer {token}

Query Parameters:
- tail: integer (default: 100)

Response 200:
{
  "status": "success",
  "file": "docker-compose.portainer.yml",
  "logs": "..."
}

📂 Structure des Fichiers

Backend

backend/app/services/
├── update_service.py      # Service de mise à jour des images
├── compose_manager.py     # Manager des docker-compose
└── docker_service.py      # Service Docker existant

backend/app/api/endpoints/
├── docker.py              # Endpoints Docker (mis à jour)
└── compose.py             # Endpoints Docker Compose (nouveau)

Frontend (À implémenter)

frontend/src/
├── views/
│   ├── ImagesView.vue     # Gestion des images
│   └── UpdatesView.vue    # Gestion des mises à jour
│
└── components/
    ├── ImageList.vue
    ├── UpdateChecker.vue
    ├── ComposeManager.vue
    └── ComposeLogs.vue

🐳 Docker Compose References

Localisation

/home/innotex/Docker/

Applications Disponibles

• portainer - Gestion Docker UI
• sonarr - Gestionnaire de séries TV
• radarr - Gestionnaire de films
• qbittorrent - Client torrent
• jellyfin - Serveur média open-source
• plex - Serveur média premium
• nextcloud - Cloud self-hosted
• nginx - Serveur web / proxy
• pihole - DNS ad-blocker
• homeassistant - Domotique
• watchtower - Mise à jour automatique
• monitoring - Prometheus + Grafana

🔑 Labels personnalisés (TrueNAS Scale Style)

labels:
  # Identifiant unique
  com.innotexboard.app: "app-name"
  
  # Catégorie fonctionnelle
  com.innotexboard.category: "Media|Network|Cloud|Management|..."
  
  # Description lisible
  com.innotexboard.description: "Description"
  
  # Version actuelle
  com.innotexboard.version: "version"
  
  # Activer/désactiver les mises à jour auto
  com.innotexboard.update-enabled: "true"
  
  # URL d'accès
  com.innotexboard.url: "http://localhost:port"

🚀 Utilisation Rapide

Via cURL

# Vérifier les mises à jour disponibles
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8000/api/v1/docker/images/check-all-updates

# Lancer un service
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8000/api/v1/docker/compose/portainer/start

# Vérifier le statut
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8000/api/v1/docker/compose/portainer/status

# Récupérer les logs
curl -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8000/api/v1/docker/compose/portainer/logs?tail=50

# Mettre à jour une image
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"new_image":"portainer/portainer-ce","new_tag":"latest"}' \
  http://localhost:8000/api/v1/docker/containers/{container_id}/update-image

# Nettoyer les images orphelines
curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  http://localhost:8000/api/v1/docker/images/prune

📋 Checklist de Déploiement

• Backend: Services update_service.py et compose_manager.py créés
• Backend: Endpoints Docker mis à jour
• Backend: Endpoints Compose créés
• Backend: Routes mises à jour
• Docker: /home/innotex/Docker créé avec 11 docker-compose de référence
• Docker: Labels de versioning ajoutés
• Frontend: UI pour images (À implémenter)
• Frontend: UI pour mises à jour (À implémenter)
• Frontend: UI pour docker-compose (À implémenter)
• Documentation: README créé
• Tests: API testée

🐛 Troubleshooting

"Docker n'est pas accessible"

# Vérifier que Docker est accessible
docker ps

# Vérifier les permissions du socket
ls -la /var/run/docker.sock

# Ajouter l'utilisateur au groupe docker
sudo usermod -aG docker $USER

"Timeout lors de la mise à jour"

# Les timeouts peuvent survenir sur les connexions lentes
# Augmenter le timeout dans update_service.py
# ou tirer directement l'image:
docker pull portainer/portainer-ce:latest

"Erreur: Impossible de supprimer le conteneur"

# Le conteneur est peut-être verrouillé
# Forcer avec:
docker rm -f container_name

📚 Ressources

• Docker Registry V2 API
• Docker Compose CLI
• TrueNAS Scale Documentation
• Portainer Docs

📝 Notes d'Implémentation

Points Forts

✅ Architecture similaire à TrueNAS Scale
✅ Support du versionning sémantique
✅ API centralisée pour Docker et docker-compose
✅ Gestion des labels pour identification
✅ Nettoyage automatique des images

Améliorations Futures

🔜 Interface web complète (frontend)
🔜 Support des webhooks Docker
🔜 Notifications de mise à jour
🔜 Historique des mises à jour
🔜 Rollback automatique en cas d'erreur
🔜 Mise à jour programmée (cron)
🔜 Support des registries privés