Docker Compose : build ou image sur un VPS ?
Comprenez pourquoi `docker compose up` ignore une modification du Dockerfile, ce que font `build` et `image`, et quelle commande utiliser sur un VPS.
Docker Compose : différence entre build et image, réponse courte
Dans un fichier Docker Compose, image: indique l’image à utiliser, notamment une image locale, un tag ou une référence par digest, tandis que build: indique à Compose comment en construire une à partir des sources. Si vous définissez uniquement image:, Compose utilise ou télécharge l’image selon pull_policy. Si vous définissez uniquement build:, Compose construit l’image avec le builder configuré et lui attribue un nom dérivé du nom du projet et de celui du service. Si vous définissez les deux, pull_policy détermine si Compose télécharge ou construit l’image. Lorsqu’il la construit, Compose lui attribue le nom indiqué dans image:. C’est ainsi que vous construisez une image, puis la poussez sous le nom de votre choix. Le builder peut s’exécuter localement ou sur un hôte Docker distant.
C’est toute la distinction. La suite explique ce que cela implique en pratique sur un serveur. Docker Engine et le plugin Compose sont supposés déjà installés ; exécuter Docker sur un VPS couvre cette partie.
Les trois formes complètes
Utilisez une image publiée et téléchargez-la si elle est absente, selon la stratégie de téléchargement par défaut. Aucun Dockerfile n’intervient.
services:
web:
image: nginx:1.27
restart: unless-stopped
ports:
- "80:80"Construisez l’image à partir d’un Dockerfile situé dans le répertoire du projet. Le build peut également télécharger les images et les dépendances nécessaires au Dockerfile.
services:
web:
build: .
restart: unless-stopped
ports:
- "80:80"Construisez l’image et marquez le résultat avec docker compose build ; sans stratégie de téléchargement explicite, up tente de télécharger cette image avant de la construire. docker compose push peut ensuite envoyer ce tag précis vers un registry.
services:
web:
build:
context: .
dockerfile: Dockerfile
image: registry.example.com/acme/web:1.4.2
restart: unless-stopped
ports:
- "80:80"context est le répertoire envoyé au builder. dockerfile est résolu par rapport à ce contexte ; context: . avec dockerfile: docker/prod.Dockerfile est donc normal et correct. Exécutez docker compose images pour afficher le nom et l’ID de l’image associés à chaque conteneur de service ; consultez le fichier Compose pour vérifier si le service utilise image:, build: ou les deux.
Pourquoi docker compose up ne reconstruit-il pas l’image après une modification du Dockerfile ?
Parce qu’un up ordinaire réutilise une image existante, sauf si vous demandez une compilation ou configurez une stratégie qui l’impose.
Lorsque Compose démarre un service qui contient uniquement une section build:, il utilise l’image existante si elle est disponible. Il ne lit pas votre Dockerfile, ne compare pas vos fichiers source et ne vérifie aucun horodatage. Avec image: et build:, mais sans pull_policy explicite, Compose tente d’abord une extraction, puis effectue la build si l’image est absente du registre ou du cache de la plateforme. Une image présente est considérée comme suffisante.
Vous modifiez donc app.py, exécutez docker compose up -d, voyez Compose indiquer que le conteneur est en cours d’exécution, mais l’ancien code est toujours servi. Rien n’a échoué, donc aucun avertissement n’a été affiché. L’indice se trouve dans le mot d’état que Compose affiche à côté du nom du conteneur : un conteneur remplacé par Compose indique qu’il a été recréé ou démarré, tandis qu’un conteneur que Compose a décidé de conserver indique qu’il est en cours d’exécution.
Deux vérifications permettent de trancher. docker compose images affiche l’identifiant de l’image utilisée par chaque conteneur. Notez-le avant le déploiement et comparez-le ensuite. docker image ls contient une colonne CREATED, mais les builds en cache et les horodatages reproductibles signifient que cette date seule ne permet pas de confirmer que votre dernière version du code source a été compilée.
Indicateurs qui forcent une reconstruction
docker compose up -d --buildconstruit d’abord les images, puis recrée les conteneurs dont l’image a changé. C’est l’indicateur recherché dans la plupart des cas.docker compose build webconstruit un service sans rien démarrer. Faites-le suivre dedocker compose up --no-deps -d webpour remplacer uniquement ce conteneur et laisser le reste de la stack fonctionner.docker compose build --no-cache webignore les layers mis en cache et reconstruit le service.docker compose build --pulltente de récupérer une version plus récente de l’image de base dansFROM. Ainsi, un tag mutable commenode:22utilise son contenu actuel plutôt que la copie téléchargée en mars.docker compose up -d --force-recreateforce la recréation des conteneurs, même si la configuration et l’image n’ont pas changé. Cet indicateur ne demande pas lui-même de build, maisuppeut quand même construire une image si elle est absente ou si la pull policy l’exige. L’utiliser alors que vous vouliez--buildest une impasse fréquente.
Vous pouvez aussi déplacer cette décision dans le fichier. Selon les termes de la spécification Compose, pull_policy: build signifie que Compose construit l’image et la reconstruit si elle est déjà présente. Chaque up entraîne alors un build, ce qui convient sur un laptop, mais rarement sur un serveur.
services:
web:
build: .
image: registry.example.com/acme/web:dev
pull_policy: buildUne autre interaction mérite d’être connue. docker compose pull tente également de récupérer les images des services qui possèdent une section build. Si cette récupération échoue, il indique que l’image doit être construite. Passez --ignore-buildable pour ignorer ces services sans afficher de message.
Comment le cache de build détermine la durée de votre déploiement
Le builder vérifie chaque instruction du Dockerfile pour trouver un résultat réutilisable dans le cache lorsque cette instruction et ses entrées sont inchangées. Pour COPY, les entrées incluent le contenu et les métadonnées des fichiers, mais excluent les dates de modification. Dès qu’une couche n’est plus disponible dans le cache, les étapes suivantes qui en dépendent sont reconstruites.
Cette seule règle détermine si votre déploiement prend quelques secondes ou plusieurs minutes. Organisez le Dockerfile en plaçant d’abord les éléments qui changent rarement, puis ceux qui changent à chaque commit.
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]npm ci se trouve au-dessus de COPY . .. Modifier un fichier source laisse donc la couche d’installation dans le cache, et le build reprend à l’étape de copie. Si vous inversez ces deux lignes, une modification d’un seul caractère réinstalle toutes les dépendances, car COPY . . invalide la couche sur laquelle npm ci est construit. La même structure s’applique à pip install -r requirements.txt et à go mod download.
--no-cache est l’outil adapté lorsque vous pensez qu’une couche obsolète masque votre correctif. Ce n’est pas un bon choix par défaut, car il supprime la réutilisation que l’ordre du Dockerfile est précisément conçu à favoriser.
Les image sets et Compose peuvent remplacer un élément : le CMD du Dockerfile définit ce que l’image exécute par défaut, tandis qu’une clé command: dans le service le remplace. Fonctionnement conjoint de command et entrypoint est important ici, car une surcharge Compose peut faire se comporter une image fraîchement construite exactement comme l’ancienne.
Contexte de build et .dockerignore
context: . rend le répertoire du projet disponible pour le builder. Sans exclusions, cela inclut .git et tout répertoire de données que vous conserveriez à côté du code source, même si BuildKit ignore les fichiers inutilisés et ne transfère que les modifications. Si un build reste bloqué à l’étape de transfert du contexte alors que le projet n’a pas changé, cela indique que le contexte est trop volumineux.
Un fichier .dockerignore à la racine du contexte exclut des chemins de ce transfert. La syntaxe est proche de celle de .gitignore.
.git
node_modules
*.log
data/
.envCela présente deux avantages. Le transfert est plus court, ce qui réduit le temps consacré à l’envoi de ces fichiers. De plus, COPY . . ne peut plus copier .env dans l’image, où toute personne qui récupère cette image peut ensuite le lire.
Le cas de build qui ralentit progressivement concerne les bind mounts. Un volume nommé se trouve en dehors du répertoire du projet, mais un bind mount tel que ./data:/var/lib/postgresql/data se trouve dans le contexte de build. Vos builds ralentissent donc chaque semaine à mesure que la base de données grossit. Une ligne dans .dockerignore suffit à corriger le problème. Bind mounts et volumes nommés présente le compromis général.
Les arguments de build présentent une version moins importante du même risque. Les valeurs transmises via args: peuvent rester dans l’historique de l’image ou dans les métadonnées de provenance. Utilisez-y donc un numéro de version, jamais un token. Les arguments proxy prédéfinis sont exclus du cache de build et de docker history par défaut, sauf s’ils sont explicitement référencés dans le Dockerfile. Fichiers env et secrets dans Compose explique plutôt où placer les identifiants.
Faut-il construire sur le VPS ou ailleurs, puis récupérer l’image ?
Construire sur le serveur qui reçoit votre trafic est le choix par défaut, car c’est le chemin le plus court : git pull, puis docker compose up -d --build. Cela convient sur un petit serveur dont personne ne dépend encore. Cette approche devient problématique pour deux raisons mesurables et une troisième qui n’apparaît que les mauvais jours.
Mémoire. Une build exécute les compilateurs et les bundlers à côté de votre application en production, et ce sont les composants les plus gourmands en mémoire dans la plupart des stacks. Un bundler JavaScript ou une compilation Rust peut épuiser la mémoire disponible sur un VPS de 1 GB. En cas d’épuisement de la mémoire, le kernel sélectionne un processus à tuer comme victime de l’OOM en utilisant un score de gravité fondé sur la consommation mémoire, le contexte de l’allocation et oom_score_adj ; il ne tue pas simplement le processus le plus volumineux. La build peut s’arrêter avec Killed et le code de sortie 137, ou votre base de données peut être tuée à sa place et le site peut tomber au milieu d’un déploiement. dmesg -T | grep -i oom recherche les messages OOM dans le log du kernel ; son utilisation nécessite l’autorisation de lire ce log.
Disque. Les builds laissent derrière elles des layers d’image et un cache de build. docker system df affiche leur utilisation du disque ; le garbage collection périodique de BuildKit libère le cache selon les règles configurées. Libérez l’espace avec docker image prune pour les images dangling et docker builder prune pour les layers mis en cache. Un disque plein bloque davantage que la build. La base de données cesse également d’écrire, et cette panne coûte beaucoup plus cher qu’un déploiement lent.
Reproductibilité. Sans la pousser ni l’exporter, une image construite sur le serveur n’existe que sur ce serveur. Si l’ancienne image n’est plus disponible, un rollback consiste à revenir à l’ancien commit et à reconstruire l’image. Cette build ne garantit toutefois pas de produire la même image, car le tag de base a changé et les mirrors de packages ont eux aussi changé. Construire ailleurs et pousser un tag transforme le rollback en simple modification : pointez image: vers le tag précédent et exécutez docker compose up -d.
L’organisation qui tient dans la durée est simple. Votre continuous integration exécute la build et pousse registry.example.com/acme/web:<git-sha>, tandis que le fichier Compose du VPS contient image: sans aucune clé build:. Le déploiement se résume alors à deux commandes qui consomment presque aucune mémoire.
docker compose pull
docker compose up -dExécutez docker login registry.example.com sur le serveur pour enregistrer les credentials nécessaires à la récupération des tags privés.
Conservez la section de build pour le développement au lieu de la supprimer, dans un fichier que vous nommez vous-même.
# compose.dev.yaml
services:
web:
build:
context: .
pull_policy: builddocker compose -f compose.yaml -f compose.dev.yaml up -d --buildNommez ce fichier compose.dev.yaml et non compose.override.yaml. Compose charge automatiquement un fichier d’override lorsqu’il est présent. Un override laissé par erreur sur le serveur relancerait donc discrètement les builds sur celui-ci. Superposer plusieurs fichiers Compose explique comment la fusion résout chaque clé.
Le piège d’architecture lorsque vous construisez ailleurs
Une image de plateforme unique contient l’architecture CPU pour laquelle elle a été construite. Si vous construisez une image ARM sur un ordinateur portable Apple Silicon, que vous la poussez, puis que vous l’utilisez sur un VPS x86_64, Docker affiche un avertissement lors de la création du conteneur s’il utilise une image en cache incompatible sans plateforme explicitement définie. Sans émulation, le processus échoue avec exec format error. Ce message ressemble à une erreur de binaire corrompu, mais ce n’en est pas une. Construisez explicitement pour la cible :
docker buildx build --platform linux/amd64 \
-t registry.example.com/acme/web:1.4.2 --push .Le même problème d’architecture se produit dans l’autre sens si votre ordinateur portable est en x86 et que vous exécutez un VPS ARM plutôt qu’un VPS x86. Laissez la CI construire sur l’architecture sur laquelle vous déployez afin d’éviter ce problème. Une image multiplateforme résout également ce problème : Docker sélectionne la variante correspondante lors de son téléchargement.
Vérifications à effectuer après un déploiement
docker compose imagesaffiche l’image et le tag utilisés par chaque conteneur en cours d’exécution. Un ID d’image différent prouve que la nouvelle build est en service.docker compose configaffiche le fichier fusionné après le remplacement des variables. Vous pouvez ainsi lire le nom final de l’image que Compose utilisera avant d’exécuter quoi que ce soit.docker compose logs -f webpendant la première demi-minute qui suit le basculement. Un conteneur qui démarre puis s’arrête redémarre uniquement si sa restart policy le prévoit ; consultez les logs pour en connaître la cause.docker image lsaffiche une colonne CREATED. Vérifiez également la sortie de la build et l’ID de l’image déployée, car l’horodatage de création seul ne prouve pas qu’une nouvelle build a été exécutée.
Si vous êtes encore en train de constituer le fichier concerné par ces vérifications, les bases d’un fichier Compose sur un VPS présente les clés associées, et l’aide-mémoire des commandes Compose répertorie les autres sous-commandes.
FAQ
Puis-je utiliser build et image dans le même service ?
Oui. C’est la configuration normale pour un projet que vous construisez vous-même. Lorsque Compose construit l’image à partir de la section build:, il étiquette le résultat avec la valeur de image:. Sans pull_policy explicite, up tente d’abord de télécharger l’image. Cette étiquette est celle que docker compose push envoie vers un registry et qu’une autre machine télécharge. Sans clé image:, Compose construit quand même l’image, mais la nomme d’après le projet et le service. Il avertit alors que l’attribut manquant empêche le push de l’image.
Pourquoi docker compose up ne prend-il pas en compte ma modification du Dockerfile ?
Parce que up réutilise normalement une image existante, sauf si vous demandez un build ou configurez une policy qui l’impose. Il ne compare pas cette image au Dockerfile ni aux fichiers source pour déterminer si un rebuild est nécessaire. Exécutez docker compose up -d --build, ou exécutez docker compose build web suivi de docker compose up --no-deps -d web pour remplacer un seul service. Définir pull_policy: build sur le service force un rebuild à chaque up. Cette configuration convient à une machine de développement.
Quelle est la différence entre --build et --force-recreate ?
--build reconstruit l’image, puis recrée les conteneurs dont l’image a changé. --force-recreate force la recréation des conteneurs même si la configuration et l’image n’ont pas changé. Cette option ne demande pas elle-même de build. Si votre modification concerne le code source ou le Dockerfile, --build est l’option à utiliser. --force-recreate sert à réinitialiser le conteneur lui-même, par exemple pour effacer sa couche inscriptible tout en conservant la même image.
Dois-je construire mes images Docker sur le VPS ou ailleurs ?
Construisez-les ailleurs, puis téléchargez une étiquette une fois que le serveur sert également du trafic. Le build se partage la mémoire avec votre application. En cas d’épuisement de la mémoire, le kernel sélectionne un processus à terminer en fonction d’un score OOM configurable. Il peut cibler le build ou votre base de données. Les builds laissent également du cache sur le disque, même si BuildKit le récupère automatiquement selon ses policies de garbage collection. Construire sur le serveur reste acceptable pour un petit projet sans utilisateurs. Le déplacement ultérieur est simple si vous conservez la section build: dans un fichier Compose réservé au développement.
Comment empêcher le cache du build Docker de remplir mon disque ?
Exécutez docker system df pour voir l’espace occupé séparément par vos images et votre cache de build. docker builder prune supprime les layers mis en cache et docker image prune supprime les images dangling laissées par les builds précédents. Ajouter -a supprime tout le cache de build inutilisé ou toutes les images non référencées par des conteneurs, respectivement. Cela ne garantit pas que le prochain build repartira entièrement de zéro. Ne planifiez pas docker system prune -af --volumes sur un serveur, car cette commande supprime les conteneurs arrêtés et les volumes anonymes inutilisés. Elle peut ainsi mettre en danger les données d’une base de données stockées dans un volume anonyme pendant la maintenance.