Commandes Docker Compose essentielles

Introduction : piloter votre application avec la CLI Compose

Avoir un fichier `docker-compose.yml` bien structuré est la première étape, mais sa véritable utilité se révèle à travers les commandes que Docker Compose met à disposition pour interagir avec votre application. Ces commandes, accessibles via `docker compose ...` (ou l'ancien `docker-compose ...`), vous permettent de gérer l'ensemble du cycle de vie de votre pile applicative de manière simple et cohérente.

Plutôt que de manipuler chaque conteneur individuellement avec `docker run`, `docker stop`, `docker rm`, etc., vous utiliserez des commandes Compose qui opèrent sur l'ensemble des services définis dans votre fichier de configuration. Elles s'occupent de créer les réseaux, les volumes, de démarrer les conteneurs dans le bon ordre (en respectant `depends_on`), et de les arrêter proprement.

Cette section détaille les commandes Docker Compose les plus fréquemment utilisées et indispensables au quotidien. Nous couvrirons leur syntaxe de base, les options courantes et illustrerons leur utilisation par des exemples concrets. Maîtriser ces commandes est la clé pour exploiter pleinement la puissance de Docker Compose.

`docker compose up` : démarrer et créer votre application

C'est la commande fondamentale pour lancer votre application définie dans le fichier `docker-compose.yml`. Elle effectue plusieurs actions :

• Vérifie la configuration dans le fichier Compose.
• Crée les réseaux et les volumes définis s'ils n'existent pas déjà.
• Crée et démarre les conteneurs pour chaque service. Si un service utilise l'option `build`, Compose construira l'image d'abord si nécessaire.
• Attache le terminal aux flux de sortie (stdout/stderr) de tous les conteneurs, affichant les logs de manière agrégée.

docker compose up [options] [SERVICE...]

• -d ou --detach : Démarre les conteneurs en arrière-plan (mode détaché) et affiche uniquement les noms des conteneurs démarrés. C'est l'option la plus utilisée pour lancer des services.
• --build : Force la reconstruction des images pour les services qui ont une section `build`, même si une image existe déjà localement.
• --force-recreate : Force la recréation de tous les conteneurs, même s'ils n'ont pas changé depuis le dernier `up`. Utile si l'état interne d'un conteneur est corrompu.
• --no-deps : Ne démarre pas les services liés par `depends_on`.
• --scale SERVICE=NUM : Permet de démarrer plusieurs instances d'un service spécifique (scaling).

# Démarre tous les services en arrière-plan
docker compose up -d

# Démarre uniquement les services 'web' et 'db' en arrière-plan
docker compose up -d web db

# Démarre en arrière-plan et force la reconstruction de l'image du service 'api'
docker compose up -d --build api

Lorsque vous exécutez `docker compose up` à nouveau, Compose compare l'état actuel avec la configuration du fichier. Il ne recrée que les conteneurs dont la configuration (image, commandes, variables d'environnement, etc.) ou les dépendances (volumes, réseaux) ont changé, laissant les autres intacts, sauf si vous utilisez `--force-recreate`.

`docker compose down` : arrêter et supprimer votre application

C'est la commande symétrique de `up`. Elle permet d'arrêter proprement et de supprimer les ressources créées par `docker compose up` pour votre application.

• Arrête tous les conteneurs définis dans le fichier Compose pour ce projet.
• Supprime les conteneurs arrêtés.
• Supprime les réseaux créés par Compose (sauf s'ils sont marqués comme `external`).

docker compose down [options]

• -v ou --volumes : Très important ! Supprime également les volumes nommés définis dans la section `volumes` du fichier Compose et utilisés par les services. Attention : cela efface les données persistantes ! A utiliser lorsque vous voulez réinitialiser complètement l'état, par exemple en développement ou en test.
• --rmi : Supprime les images utilisées par les services. Le `type` peut être :
  • all : Supprime toutes les images utilisées par les services.
  • local : Supprime uniquement les images qui n'ont pas de tag personnalisé (builds locaux).
• --remove-orphans : Supprime les conteneurs de services qui ne sont plus définis dans le fichier Compose actuel mais qui avaient été lancés précédemment pour ce projet.

# Arrête et supprime les conteneurs et réseaux
docker compose down

# Arrête et supprime conteneurs, réseaux ET volumes nommés
docker compose down -v

# Arrête, supprime tout (conteneurs, réseaux, volumes) ET toutes les images associées
docker compose down -v --rmi all

La commande `down` est essentielle pour nettoyer votre environnement après avoir travaillé sur un projet ou avant de relancer une configuration complètement nouvelle.

`docker compose ps` : lister les conteneurs de l'application

Cette commande est l'équivalent de `docker ps` mais filtrée pour n'afficher que les conteneurs associés à votre projet Compose (défini par le répertoire courant ou l'option `-p`). Elle montre l'état actuel (en cours, arrêté), les ports mappés, etc.

docker compose ps [options] [SERVICE...]

• -a ou --all : Affiche tous les conteneurs du projet, y compris ceux qui sont arrêtés.
• --filter : Filtre les conteneurs par état (`running`, `exited`, `paused`).
• --services : Affiche uniquement les noms des services.

# Affiche les conteneurs en cours du projet
docker compose ps

# Affiche tous les conteneurs (actifs et arrêtés) du projet
docker compose ps -a

`docker compose logs` : consulter les logs des services

Indispensable pour le débogage, cette commande agrège et affiche les logs (stdout/stderr) de tous les services de votre application, ou de services spécifiques.

docker compose logs [options] [SERVICE...]

• -f ou --follow : Suit la sortie des logs en temps réel (comme `tail -f`). Appuyez sur `Ctrl+C` pour arrêter.
• --tail= : Affiche les N dernières lignes de log pour chaque service.
• -t ou --timestamps : Ajoute un timestamp au début de chaque ligne de log.
• --no-log-prefix : N'affiche pas le préfixe du nom du service devant chaque ligne.

# Affiche les logs de tous les services et quitte
docker compose logs

# Suit les logs en temps réel pour tous les services
docker compose logs -f

# Suit les logs uniquement pour les services 'web' et 'api'
docker compose logs -f web api

# Affiche les 100 dernières lignes de log du service 'db'
docker compose logs --tail=100 db

`docker compose exec` : exécuter une commande dans un service en cours

Permet d'exécuter une commande à l'intérieur d'un conteneur déjà en cours d'exécution pour un service donné. C'est l'équivalent de `docker exec` mais appliqué à un service Compose.

docker compose exec [options] SERVICE COMMANDE [ARGS...]

• -d ou --detach : Exécute la commande en arrière-plan.
• -e VAR=VAL : Définit des variables d'environnement pour la commande.
• -T : Désactive l'allocation d'un pseudo-TTY. Utile pour les scripts.
• -u ou --user : Exécute la commande en tant qu'utilisateur spécifié.

# Ouvre un shell interactif dans le conteneur du service 'web'
docker compose exec web /bin/sh

# Liste les fichiers dans /app du conteneur du service 'api'
docker compose exec api ls /app

# Exécute une tâche de base de données dans le service 'db' en tant qu'utilisateur 'postgres'
docker compose exec -u postgres db psql -d mydatabase -c "VACUUM ANALYZE;"

`docker compose run` : exécuter une commande ponctuelle dans un nouveau conteneur

Contrairement à `exec` qui cible un conteneur existant, `run` démarre un nouveau conteneur pour le service spécifié afin d'y exécuter une commande unique. Ce nouveau conteneur partage la configuration du service (image, variables d'environnement, réseaux, volumes) mais n'hérite pas des ports mappés (pour éviter les conflits). Une fois la commande terminée, le conteneur est arrêté (mais pas supprimé par défaut, sauf avec `--rm`).

C'est idéal pour des tâches ponctuelles comme les migrations de base de données, l'exécution de tests, l'ouverture d'un shell pour inspecter l'environnement défini par le service, ou l'utilisation d'un outil en ligne de commande fourni par l'image du service.

docker compose run [options] SERVICE [COMMANDE [ARGS...]]

• -d ou --detach : Exécute en arrière-plan.
• --rm : Supprime automatiquement le conteneur une fois la commande terminée. Fortement recommandé pour éviter l'accumulation de conteneurs arrêtés.
• -e VAR=VAL : Variables d'environnement supplémentaires.
• --service-ports : Mappe les ports définis dans la configuration du service (à utiliser avec prudence).
• --no-deps : Ne démarre pas les services liés par `depends_on`.
• -v /hote:/cont, -p HOST:CONT : Permet de spécifier des volumes ou ports additionnels pour cette exécution ponctuelle.

# Exécute les migrations de base de données (commande définie dans l'image 'api') et supprime le conteneur
docker compose run --rm api python manage.py migrate

# Ouvre un shell interactif dans un nouveau conteneur basé sur le service 'web'
docker compose run --rm web /bin/sh

# Installe une dépendance avec npm dans le service 'frontend'
docker compose run --rm frontend npm install some-package

Comprendre la différence entre `exec` (commande dans un conteneur existant) et `run` (commande dans un nouveau conteneur) est crucial pour utiliser Compose efficacement.

`docker compose build` et `docker compose pull` : gérer les images

Ces commandes permettent de gérer les images Docker associées aux services définis dans votre fichier Compose.

# Construit les images pour tous les services nécessitant un build
docker compose build

# Force la reconstruction de l'image pour le service 'api' sans utiliser le cache
docker compose build --no-cache api

# Télécharge les images pour tous les services
docker compose pull

# Télécharge l'image uniquement pour le service 'db'
docker compose pull db

`docker compose start`, `stop`, `restart`, `pause`, `unpause` : contrôle fin du cycle de vie

Ces commandes permettent de contrôler l'état des conteneurs existants (préalablement créés par `up` ou `run`) sans les supprimer ni les recréer. Elles sont utiles pour des arrêts/redémarrages rapides sans perdre l'état interne des conteneurs (contrairement à `down` puis `up`).

• docker compose start [SERVICE...] : Démarre les conteneurs arrêtés pour les services spécifiés (ou tous).
• docker compose stop [SERVICE...] : Arrête les conteneurs en cours pour les services spécifiés (ou tous) sans les supprimer.
• docker compose restart [SERVICE...] : Redémarre les conteneurs (équivalent à `stop` puis `start`).
• docker compose pause [SERVICE...] : Met en pause les processus dans les conteneurs spécifiés.
• docker compose unpause [SERVICE...] : Reprend les processus dans les conteneurs mis en pause.

# Arrête le service 'web'
docker compose stop web

# Redémarre tous les services
docker compose restart

`docker compose config` : validation et visualisation

Cette commande est très utile pour vérifier la syntaxe de votre fichier `docker-compose.yml` et visualiser la configuration finale après la fusion de plusieurs fichiers (si vous en utilisez), l'interpolation des variables d'environnement et la résolution des chemins relatifs.

docker compose config [options]

• -q ou --quiet : Ne produit aucune sortie si la configuration est valide, affiche une erreur sinon. Utile pour la validation dans les scripts.
• --resolve-image-digests : Affiche le digest de l'image en plus du tag.
• --services : Affiche uniquement la configuration des services.
• --volumes : Affiche uniquement la configuration des volumes.
• --networks : Affiche uniquement la configuration des réseaux.

# Valide le fichier et affiche la configuration interpolée
docker compose config

# Valide silencieusement (vérifie la syntaxe)
docker compose config -q

Options globales `-f` et `-p`

Deux options globales peuvent être utilisées avec la plupart des commandes Compose :

• -f ou --file : Permet de spécifier un ou plusieurs fichiers de configuration Compose à utiliser. Si plusieurs fichiers sont spécifiés, ils sont fusionnés (le dernier fichier ayant priorité en cas de conflit). Par défaut, Compose cherche `docker-compose.yml` puis `docker-compose.yaml` dans le répertoire courant.
• -p ou --project-name : Définit un nom de projet personnalisé. Par défaut, Compose utilise le nom du répertoire contenant le fichier `docker-compose.yml`. Le nom du projet est utilisé comme préfixe pour les noms de conteneurs, réseaux et volumes créés, assurant l'isolation entre différents projets Compose sur le même hôte.

# Utilise un fichier spécifique et donne un nom de projet personnalisé
docker compose -f docker-compose.prod.yml -p myapp-production up -d

Maîtriser ces commandes essentielles vous permettra de gérer vos applications multi-conteneurs avec aisance et efficacité, en tirant pleinement parti de la puissance déclarative de Docker Compose.