Docker Compose build : reconstruire et vérifier ses images

docker compose build construit ou reconstruit les images des services qui possèdent une définition build. Cette commande ne remplace pas un conteneur en cours d’exécution. Après la reconstruction, utilisez docker compose up pour appliquer la nouvelle image, puis vérifiez l’identifiant de l’image du conteneur et la réponse de l’application.

Ce guide suit ces étapes avec un petit service local. La configuration et le plan de construction généré ont passé les contrôles avec Docker Compose v5.1.4. Le moteur Docker Linux était indisponible pendant la préparation : la construction de l’image, le cache, le remplacement du conteneur et la réponse HTTP n’ont donc pas été testés ici.

Choisir entre build, up et restart

Commande	Utilisation	Vérification suivante
docker compose build web	Construire l’image du service web	L’identifiant de la nouvelle image locale
docker compose up -d --build web	Construire, puis créer ou mettre à jour le service	Le conteneur actif et sa réponse
docker compose up -d --no-build web	Appliquer une image déjà construite	L’image utilisée par le conteneur
docker compose restart web	Redémarrer un conteneur existant	La résolution éventuelle du problème de processus

La référence de up décrit la recréation après une modification de l’image ou de la configuration du service. restart réutilise le conteneur existant ; cette commande n’applique ni une nouvelle image ni les changements des variables d’environnement Compose. Notre guide des variables d’environnement Compose détaille ces paramètres.

Créer un exemple isolé

Prévoyez un nouveau dossier, le port 8080 disponible, Docker Compose et un moteur Docker fonctionnel utilisant des conteneurs Linux. Vérifiez docker context show et docker info avant de construire. L’exemple d’inspection des identifiants ci-dessous utilise Bash. Exécutez toutes les commandes depuis ce dossier et arrêtez-vous si l’une d’elles échoue.

Créez un dossier site et enregistrez ce fichier sous site/index.html :

<!doctype html>
<html lang="en"><meta charset="utf-8"><title>Build demo</title>
<h1>Build version 1</h1></html>

Enregistrez ce Dockerfile à côté du dossier site :

FROM python:3.12-slim
WORKDIR /app
COPY site/ /app/site/
USER 10001:10001
EXPOSE 8000
CMD ["python", "-m", "http.server", "8000", "--bind", "0.0.0.0", "--directory", "/app/site"]

L’image copie la page dans son système de fichiers et utilise les identifiants numériques UID/GID 10001. Le dossier source et la page doivent être lisibles par cet utilisateur. Le module Python http.server convient à cette démonstration temporaire, pas à un serveur de production. Le tag de base peut évoluer ; une construction reproductible exige un digest vérifié et des entrées maîtrisées.

Enregistrez ce fichier sous .dockerignore. Cette liste d’autorisation exclut les fichiers sans rapport avec l’exemple du contexte de construction. Placez uniquement du contenu public de démonstration dans site :

*
!Dockerfile
!site/
!site/**

Enfin, enregistrez compose.yaml :

name: compose-build-demo
services:
  web:
    image: compose-build-demo-web:local
    pull_policy: never
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - "127.0.0.1:8080:8000"

build.context désigne les fichiers accessibles au constructeur. Ici, il correspond au dossier contenant compose.yaml ; dockerfile indique la recette dans ce contexte. image nomme le résultat. Ces relations sont décrites dans la spécification de construction Compose.

Le paramètre pull_policy: never conserve l’image applicative du service en local. Il est distinct du téléchargement de l’image de base du Dockerfile pendant une construction explicite. Le port 8080 est exposé uniquement sur l’adresse de boucle locale de l’hôte. Aucun montage de dossier n’est utilisé : modifier la page source ne modifie donc pas directement la copie du conteneur actif.

Valider le modèle avant la construction

docker compose -f compose.yaml config --quiet
docker compose -f compose.yaml config --format json

La commande config doit résoudre un seul service web, le contexte attendu, l’image compose-build-demo-web:local et la correspondance entre 127.0.0.1:8080 et le port 8000 du conteneur. Elle vérifie le modèle Compose, pas la construction du Dockerfile ni le démarrage du conteneur.

Nos contrôles ont également généré le résultat de docker compose -f compose.yaml build --print web et vérifié sa cible, le chemin du Dockerfile et le tag de l’image. Cette commande affiche un plan sans l’exécuter. Ce résultat permet une inspection ; il ne prouve pas qu’une image a été construite.

Construire l’image et démarrer le service

docker compose -f compose.yaml build --pull web
docker compose -f compose.yaml up -d --no-build --pull never web
docker compose -f compose.yaml ps
curl --fail http://127.0.0.1:8080/

Exécutez chaque ligne seulement après la réussite de la précédente. La première demande une vérification de l’image de base. La deuxième utilise l’image applicative locale sans la reconstruire ni en télécharger une autre. La page attendue contient Build version 1 : vérifiez ce résultat sur votre machine. Si le port 8080 est occupé, changez le port publié dans Compose et adaptez la requête.

docker compose up -d --build web regroupe construction et démarrage. Séparer les étapes aide à localiser un échec. La réussite d’une construction ne démontre pas le bon fonctionnement du service.

Identifier l’image réellement utilisée

Dans Bash, exécutez :

docker image inspect compose-build-demo-web:local --format '{{.Id}}'
cid=$(docker compose -f compose.yaml ps -q web)
if [ -z "$cid" ]; then
  echo "No running web container" >&2
  exit 1
fi
docker inspect "$cid" --format '{{.Image}}'

La première commande inspecte l’image actuellement associée au tag local. La dernière inspecte l’image enregistrée dans le conteneur actif. Pour cette construction locale sur une seule plateforme, comparez les identifiants. Le champ Config.Image du conteneur contient sa référence d’image, qui peut garder le même tag entre plusieurs constructions ; il ne suffit pas à prouver une mise à jour. La référence inspect décrit la sélection des champs.

Modifier un fichier, reconstruire et recréer

Modifiez le titre de site/index.html pour afficher Build version 2, puis lancez :

docker compose -f compose.yaml build web

Avant d’exécuter up, répétez les vérifications d’identifiants et la requête HTTP. Le conteneur actif utilise toujours son système de fichiers initial. La réponse attendue reste la version 1, même si le tag local désigne maintenant une image reconstruite contenant la page modifiée.

docker compose -f compose.yaml up -d --no-build --pull never web
curl --fail http://127.0.0.1:8080/

Comparez de nouveau les identifiants et vérifiez la version 2 dans la réponse. Examinez les deux : un identifiant correct n’exclut pas un cache navigateur, une mauvaise configuration applicative ou un montage masquant des fichiers de l’image. Cet exemple ne comporte volontairement aucun montage.

Ajoutez --force-recreate à up seulement si vous souhaitez imposer un remplacement indépendamment de la détection des changements. Cette option ne reconstruit pas l’image. Pour automatiser les modifications pendant le développement, consultez notre guide Compose Watch (en anglais).

Distinguer no-cache et pull

--no-cache désactive la réutilisation du cache de construction pour cette opération ; --pull demande de vérifier si une image de base plus récente existe. Une option n’implique pas l’autre. Pour demander les deux :

docker compose -f compose.yaml build --no-cache --pull web

Ces options figurent dans la référence Compose build. Elles ne corrigent ni un mauvais contexte, ni un fichier ignoré, ni un conteneur qui n’a pas été recréé. --pull ne peut pas non plus remplacer un digest explicitement fixé par un autre.

Modifier le contenu d’un fichier copié invalide normalement l’entrée correspondante du cache COPY. Modifier uniquement son horodatage ne suffit pas. Les règles du cache Docker expliquent cette distinction. Évitez de supprimer le cache systématiquement lorsque le problème vient du chemin ou du démarrage.

Diagnostiquer l’étape en échec

• Connexion à Docker impossible : vérifiez le contexte sélectionné et la disponibilité du moteur. Un fichier Compose valide ne démarre pas le moteur.
• Fichier absent pendant COPY : vérifiez le contexte, la casse du nom et .dockerignore. Une instruction COPY ordinaire ne peut pas accéder aux fichiers situés hors du contexte.
• Nouvelle image, ancien comportement : comparez les identifiants, recréez le service et vérifiez les montages et les caches de réponse.
• Téléchargement d’une dépendance privée impossible : vérifiez l’accès au registre ou au paquet. Utilisez des montages de secrets de construction pour les identifiants, sans les intégrer aux arguments de construction ou aux couches de l’image.

Pour un déploiement avec Compute with Hivenet, notre guide pour exécuter Docker sur une VM (en anglais) présente la préparation de l’hôte. Cet exemple local ne valide ni un déploiement Hivenet ni une configuration de serveur web de production.

Arrêter l’exemple temporaire

docker compose -f compose.yaml down

Exécutez cette commande uniquement depuis le dossier de l’exemple, avec le même fichier Compose et le même projet. Elle supprime les conteneurs et le réseau du projet ; l’image construite reste disponible. Il n’est pas nécessaire de supprimer les images, conteneurs ou volumes des autres projets.