Fichiers override Docker Compose : fusionner et vérifier

Un fichier override Docker Compose modifie certaines parties d’une configuration de base. Vous pouvez conserver les réglages communs des services dans compose.yaml, puis ajouter les différences nécessaires au développement local ou à un autre environnement. Examinez ensuite le modèle fusionné : une valeur ultérieure peut remplacer, compléter ou fusionner une valeur précédente.

Ce guide utilise un petit exercice de configuration pour vérifier la sélection des fichiers, les variables d’environnement, les commandes, les ports et les montages bind. Quatorze contrôles ont réussi avec Docker Compose v5.1.4 sous Windows. Ils utilisent le véritable CLI Compose et vérifient aussi les configurations rejetées. Le moteur Docker était indisponible : aucune image n’a été téléchargée et aucun conteneur n’a été démarré.

Choisir explicitement les fichiers

Par défaut, Compose combine compose.yaml avec le fichier facultatif compose.override.yaml. Répétez l’option -f pour sélectionner une autre liste, dans l’ordre voulu. Le guide Docker sur les fichiers multiples décrit ce fonctionnement. Une commande contenant seulement -f compose.yaml exclut le fichier override par défaut.

Exécutez l’exercice depuis son répertoire, sans réglage COMPOSE_FILE modifiant la découverte automatique. Vérifiez votre installation avec docker compose version. Les exemples utilisent la commande actuelle docker compose et des balises YAML propres à Compose, plutôt qu’un outil générique de fusion YAML.

Créer le fichier de base et un override

Créez cette arborescence, avec un court fichier index.html dans chaque répertoire de contenu. Le répertoire review et le répertoire vide overlays serviront plus loin.

override-lab/
  compose.yaml
  compose.override.yaml
  site/index.html
  preview/index.html
  review/index.html
  overlays/

Enregistrez ce fichier sous le nom compose.yaml :

services:
  web:
    image: python:3.13-alpine
    command: ["python", "-m", "http.server", "8000", "--directory", "/site"]
    environment:
      LOG_LEVEL: info
      KEEP_ME: base
    ports:
      - "127.0.0.1:8080:8000"
    volumes:
      - type: bind
        source: ./site
        target: /site
        read_only: true
        bind:
          create_host_path: false

L’image Python et le serveur HTTP donnent un sens concret aux commandes et aux montages. Il s’agit d’un exercice de configuration, pas d’un modèle de serveur web de production. LOG_LEVEL, KEEP_ME et APP_MODE sont des variables de démonstration ; le serveur HTTP de Python ne les interprète pas comme des réglages applicatifs.

Enregistrez le fichier suivant sous compose.override.yaml. Il ajoute à la commande l’option de sortie sans tampon de Python, ajuste l’environnement, ajoute un port hôte et choisit un autre répertoire pour la même destination de montage dans le conteneur.

services:
  web:
    command: ["python", "-u", "-m", "http.server", "8000", "--directory", "/site"]
    environment:
      LOG_LEVEL: debug
      APP_MODE: development
    ports:
      - "127.0.0.1:8081:8000"
    volumes:
      - type: bind
        source: ./preview
        target: /site
        read_only: true
        bind:
          create_host_path: false

Comparer le modèle de base et le modèle fusionné

Exécutez ces commandes depuis le répertoire du projet. La première lit seulement la base, la deuxième utilise la découverte automatique et la troisième nomme explicitement les deux fichiers.

docker compose -p override-lab -f compose.yaml config
docker compose -p override-lab config
docker compose -p override-lab -f compose.yaml -f compose.override.yaml config --format json

Dans nos contrôles, la découverte automatique et la commande explicite à deux fichiers ont produit des modèles JSON identiques. La base seule conservait LOG_LEVEL=info, le port 8080 et le répertoire site. Le modèle fusionné contenait les champs ci-dessous. Cet extrait omet les autres champs et abrège le chemin absolu du montage en <project>/preview.

{
  "environment": {
    "APP_MODE": "development",
    "KEEP_ME": "base",
    "LOG_LEVEL": "debug"
  },
  "command": [
    "python",
    "-u",
    "-m",
    "http.server",
    "8000",
    "--directory",
    "/site"
  ],
  "ports": [
    {
      "mode": "ingress",
      "host_ip": "127.0.0.1",
      "target": 8000,
      "published": "8080",
      "protocol": "tcp"
    },
    {
      "mode": "ingress",
      "host_ip": "127.0.0.1",
      "target": 8000,
      "published": "8081",
      "protocol": "tcp"
    }
  ],
  "volumes": [
    {
      "source": "<project>/preview",
      "target": "/site",
      "read_only": true
    }
  ]
}

docker compose config analyse les fichiers, résout les valeurs et affiche le modèle que Compose appliquerait. Sa référence de commande décrit aussi la sortie JSON et -q, qui valide sans afficher le modèle. Une validation réussie ne prouve pas la disponibilité de l’image ou des ports, les droits d’accès aux chemins hôtes, ni le bon fonctionnement de l’application.

Lire chaque fusion selon son champ

L’exemple produit quatre résultats différents :

• Environnement : LOG_LEVEL devient debug, KEEP_ME reste et APP_MODE est ajouté. Les clés sont fusionnées individuellement.
• Commande : la commande override à sept éléments remplace celle à six éléments de la base. Les listes ne sont pas concaténées.
• Ports : les ports hôtes 8080 et 8081 restent tous deux présents, chacun visant le port 8000 du conteneur. Un autre port publié crée une association distincte.
• Volumes : un seul montage reste à /site, avec preview comme source. La destination dans le conteneur identifie le montage modifié.

La spécification de fusion Docker définit ces règles. L’unicité des ports repose sur l’adresse IP, le port cible, le port publié et le protocole. Les volumes utilisent le chemin cible. Les champs de commande, dont command, entrypoint et healthcheck.test, suivent une règle de remplacement.

Dans le modèle de cet exercice, les deux adresses publiées utilisent 127.0.0.1. Notre guide réseau Compose (en anglais) explique la différence entre une association de port hôte et la communication entre services.

Remplacer ou supprimer explicitement les ports hérités

Une liste vide peut prêter à confusion. Enregistrez ce fichier sous compose.empty.yaml :

services:
  web:
    ports: []

Ajoutez-le en dernier :

docker compose -p override-lab -f compose.yaml -f compose.override.yaml -f compose.empty.yaml config

Notre modèle résolu contenait toujours les deux associations de ports. La séquence vide sans balise n’a pas effacé les entrées héritées.

Pour conserver seulement le port 8081, enregistrez ce fichier sous compose.replace.yaml :

services:
  web:
    ports: !override
      - "127.0.0.1:8081:8000"

La balise !override remplace l’attribut entier au lieu d’appliquer sa règle de fusion habituelle. Docker documente sa prise en charge à partir de Compose 2.24.4. Validez et examinez cette liste précise de trois fichiers :

docker compose -p override-lab -f compose.yaml -f compose.override.yaml -f compose.replace.yaml config -q
docker compose -p override-lab -f compose.yaml -f compose.override.yaml -f compose.replace.yaml config --format json

Notre résultat contenait seulement 127.0.0.1:8081, dirigé vers le port 8000. Les changements d’environnement et de montage provenant de compose.override.yaml étaient conservés.

Pour supprimer tous les ports publiés, utilisez cette autre option, enregistrée sous compose.reset.yaml :

services:
  web:
    ports: !reset []

docker compose -p override-lab -f compose.yaml -f compose.override.yaml -f compose.reset.yaml config

L’exemple !reset a supprimé les déclarations de ports du service tout en conservant son environnement fusionné. Retirer une déclaration de port hôte ne retire pas le service de son réseau Compose. L’exercice vérifie ces balises pour les ports ; inspectez tout autre champ balisé avec votre version de Compose avant de vous y fier.

Résoudre les chemins depuis le fichier de base

Un override placé dans un sous-répertoire ne donne pas une nouvelle base à ses chemins relatifs. Enregistrez ce fragment sous overlays/compose.review.yaml :

services:
  web:
    volumes:
      - type: bind
        source: ./review
        target: /site
        read_only: true
        bind:
          create_host_path: false

docker compose -p override-lab -f compose.yaml -f overlays/compose.review.yaml config

Dans notre modèle résolu, la source était <project>/review, et non <project>/overlays/review. Le premier fichier -f définit le répertoire de base par défaut. La référence du CLI Compose décrit l’option --project-directory permettant de changer explicitement cette base.

La syntaxe longue du montage définit create_host_path: false pour éviter la création silencieuse d’un répertoire manquant au démarrage. L’analyse de la configuration ne vérifie pas, à elle seule, que le daemon Docker peut accéder à ce répertoire. La référence des volumes détaille les options de montage bind.

Ce fragment échoue à la validation lorsqu’il est utilisé seul, car il ne définit ni image ni build. Il fonctionne avec la base, dont le service complet hérite de l’image. Pour des applications Compose maintenues indépendamment et nécessitant leurs propres bases de chemins, consultez la référence include ; ce mécanisme distinct n’est pas testé ici.

Garder visibles l’ordre des fichiers et la résolution des variables

Inversez les deux premiers fichiers pour examiner l’effet de leur ordre :

docker compose -p override-lab -f compose.override.yaml -f compose.yaml config

Notre résultat inversé rétablissait la commande de base, LOG_LEVEL=info et le montage depuis site. La variable propre au développement restait présente, ainsi que les deux ports distincts. Placer la base en dernier n’annulait donc pas tous les ajouts du premier fichier.

L’interpolation des variables s’effectue avant la fusion, séparément pour chaque fichier, comme l’indique la référence d’interpolation Docker. Une entrée environment destinée au conteneur ne fournit pas automatiquement les valeurs des expressions ${...} d’un autre fichier Compose. Notre guide des variables d’environnement (en anglais) traite cette distinction.

Si le besoin consiste à sélectionner des services facultatifs, les profils Compose (en anglais) peuvent convenir. Les overrides modifient la configuration ; un profil ne remplace pas la vérification de ces fusions.

Vérifier le modèle final avant de démarrer les conteneurs

Conservez la même liste ordonnée de fichiers entre la validation et les commandes ultérieures up, ps ou down. Vérifiez l’image résolue, la commande complète, l’environnement, les adresses publiées et les sources et destinations des montages. Retirez les informations sensibles avant de partager le modèle : une configuration réelle peut contenir des secrets résolus.

Les quatorze contrôles couvraient la sélection automatique et explicite, les remplacements et ajouts, les listes vides, les balises de ports, les chemins relatifs, l’ordre inversé, l’échec d’un fragment seul, les ports invalides et la validation silencieuse. Ils n’ont testé ni démarrage de conteneur, ni réponse HTTP, ni déploiement sur Compute with Hivenet. Après l’examen du modèle, les contrôles d’exécution constituent une étape distincte dans l’environnement choisi.