Migrer un conteneur Docker de docker run vers Docker Compose : guide complet

Docker est devenu incontournable dans le déploiement d’applications. Mais beaucoup de développeurs et d’administrateurs système commencent leur aventure avec de simples commandes docker run avant de réaliser les limites de cette approche. Quand l’infrastructure grandit, la gestion manuelle devient vite ingérable. C’est là que Docker Compose s’impose comme un outil clé.

Dans ce guide, nous allons voir comment migrer un conteneur Docker lancé avec docker run vers un fichier docker-compose.yml, étape par étape. L’objectif : ne pas perdre de données, structurer son environnement et préparer le terrain pour une exploitation plus durable, particulièrement dans un contexte professionnel où la conformité et la maintenance sont des enjeux cruciaux.

---

Pourquoi passer de docker run à Docker Compose ?

La simplicité a ses limites

La commande docker run est parfaite pour tester rapidement une image ou déployer un service isolé. Mais dès qu’il faut gérer plusieurs conteneurs, configurer des dépendances (base de données, reverse proxy, stockage persistant), ou maintenir une cohérence entre environnements, elle montre ses faiblesses.

Les avantages de Docker Compose

Avec Docker Compose, vous décrivez vos services dans un fichier YAML lisible et versionnable. Cela permet :

• de documenter et partager la configuration,
• d’assurer la reproductibilité entre machines,
• d’éviter les erreurs liées à des commandes tapées à la main,
• de gérer facilement les volumes, réseaux, variables d’environnement.

Comme le souligne la documentation officielle de Docker, Compose n’est pas qu’un outil pratique, c’est une bonne pratique pour industrialiser vos déploiements.

---

Exemple de commande docker run

Prenons un cas concret avec Open WebUI :

docker run -d -p 3000:8080 
  --add-host=host.docker.internal:host-gateway 
  -v open-webui:/app/backend/data 
  --name open-webui 
  --restart always 
  ghcr.io/open-webui/open-webui:main

Cette commande lance le service, mappe un port, ajoute un host spécial, monte un volume nommé et définit un redémarrage automatique.

Problème : cette ligne est difficile à relire, impossible à versionner efficacement et compliquée à répliquer sur un autre poste ou serveur.

---

Conversion en docker-compose.yml

Voici l’équivalent minimaliste en docker-compose.yml :

services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: open-webui
    restart: always
    ports:
      - "3000:8080"
    extra_hosts:
      - "host.docker.internal:host-gateway"
    volumes:
      - open-webui:/app/backend/data

volumes:
  open-webui:
    external: true

Quelques points à noter :

• Le volume nommé open-webui est déclaré comme external pour réutiliser celui déjà créé par docker run.
• Les données existantes ne seront pas perdues.
• Le fichier peut être versionné dans Git, partagé avec une équipe ou intégré dans une pipeline CI/CD.

---

Migrer un conteneur existant sans perte de données

Si vous avez déjà un conteneur open-webui qui tourne avec docker run, vous devez :

1. Arrêter le conteneur docker stop open-webui
2. Supprimer le conteneur sans toucher au volume docker rm open-webui ⚠️ Ne pas utiliser -v, sinon le volume sera supprimé.
3. Vérifier que le volume existe toujours docker volume ls | grep open-webui
4. Relancer avec Compose docker compose up -d

Les données sont conservées car elles sont stockées dans le volume nommé.

---

Où stocker vos fichiers docker-compose.yml ?

La convention varie selon les environnements :

• Pour un projet applicatif, placez le fichier docker-compose.yml à la racine du dépôt.
• Pour des services globaux (bases de données, reverse proxy, monitoring), il est recommandé de centraliser dans /srv (pratique sur Linux et cohérent avec la hiérarchie FHS).

Exemple d’arborescence :

/srv/
 ├── open-webui/
 │    └── docker-compose.yml
 ├── web-project/
 │    └── docker-compose.yml

Cette organisation simplifie les sauvegardes et la maintenance.

---

Mettre à jour une image avec Docker Compose

Migrer vers Compose offre aussi un gain énorme lors des mises à jour :

docker compose pull
docker compose up -d

Cela télécharge la nouvelle image, recrée le conteneur, et réutilise automatiquement vos volumes.
Pour forcer la recréation même si rien n’a changé :

docker compose up -d --force-recreate

Pour libérer de l’espace après plusieurs mises à jour, il est conseillé d’exécuter :

docker image prune

---

Bonnes pratiques de migration

1. Versionner vos fichiers Compose
   Utilisez Git pour conserver un historique et faciliter la collaboration.
2. Séparer les variables sensibles
   Placez-les dans un fichier .env plutôt que dans le YAML.
3. Tester en local avant de déployer en production
   En particulier si vous migrez plusieurs services en même temps.
4. Surveiller l’utilisation des volumes
   Vérifiez régulièrement les volumes orphelins avec docker volume ls.

---

Migrer plusieurs conteneurs à la fois

La puissance de Docker Compose réside dans la gestion multi-services. Par exemple, si votre application dépend d’une base de données PostgreSQL, vous pouvez écrire :

services:
  web:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    depends_on:
      - db
    volumes:
      - open-webui:/app/backend/data

  db:
    image: postgres:16
    environment:
      POSTGRES_USER: user
      POSTGRES_PASSWORD: pass
      POSTGRES_DB: mydb
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  open-webui:
    external: true
  pgdata:

Ici, vous orchestrez application + base de données avec un seul docker compose up -d.

---

Points à vérifier avant la migration

• Compatibilité de l’image : certaines images Docker sont optimisées pour docker run avec des options spécifiques. Vérifiez la documentation officielle de l’image.
• Options réseau personnalisées : si vous utilisiez un –network, adaptez-le dans le YAML.
• Volumes bindés : si vous montiez un dossier local (par ex. /srv/data:/app/data), assurez-vous que les droits utilisateurs sont corrects.
• Migration vers la production : certaines entreprises exigent la conformité RGPD et la traçabilité. L’utilisation de Compose facilite la documentation.

---

Conclusion

Migrer un conteneur Docker de docker run vers Docker Compose n’est pas qu’une optimisation technique. C’est une étape clé pour passer d’une expérimentation individuelle à une gestion pérenne et collaborative des services. Vous gagnez en clarté, en maintenabilité et en sécurité, tout en gardant la maîtrise de vos volumes et donc de vos données.

La migration ne demande que quelques minutes, mais apporte un cadre durable pour vos projets, qu’ils soient personnels ou professionnels. Pour un administrateur système ou un développeur, c’est un pas vers une exploitation conforme aux bonnes pratiques et aux exigences de maintenance moderne.

---