Spécification Compose Build

Build est une partie facultative de la spécification Compose. Il indique à Compose comment (re)construire une application à partir de la source et vous permet de définir le processus de construction dans un fichier Compose de manière portable. build peut être spécifié soit comme une chaîne unique définissant un chemin de contexte, soit comme une définition de construction détaillée.

Dans le premier cas, tout le chemin est utilisé comme contexte Docker pour exécuter une construction Docker, recherchant un Dockerfile canonique à la racine du répertoire. Le chemin peut être absolu ou relatif. S'il est relatif, il est résolu depuis le répertoire contenant votre fichier Compose. S'il est absolu, le chemin empêche le fichier Compose d'être portable, donc Compose affiche un avertissement.

Dans le second cas, les arguments de construction peuvent être spécifiés, incluant un emplacement Dockerfile alternatif. Le chemin peut être absolu ou relatif. S'il est relatif, il est résolu depuis le répertoire contenant votre fichier Compose. S'il est absolu, le chemin empêche le fichier Compose d'être portable, donc Compose affiche un avertissement.

Utilisation de build et image

Quand Compose est confronté à la fois à une sous-section build pour un service et un attribut image, il suit les règles définies par l'attribut pull_policy.

Si pull_policy est absent de la définition du service, Compose tente d'abord de tirer l'image puis construit depuis la source si l'image n'est pas trouvée dans le registre ou le cache de la plateforme.

Publication des images construites

Compose avec le support build offre une option pour pousser les images construites vers un registre. Ce faisant, il n'essaie pas de pousser les images de service sans attribut image. Compose vous avertit de l'attribut image manquant qui empêche les images d'être poussées.

Exemple illustratif

L'exemple suivant illustre les concepts de la Spécification Compose Build avec un exemple d'application concrète. L'exemple n'est pas normatif.

services:
  frontend:
    image: example/webapp
    build: ./webapp

  backend:
    image: example/database
    build:
      context: backend
      dockerfile: ../backend.Dockerfile

  custom:
    build: ~/custom

Quand utilisé pour construire les images de service depuis la source, le fichier Compose crée trois images Docker :

• example/webapp : Une image Docker est construite en utilisant le sous-répertoire webapp, dans le dossier parent du fichier Compose, comme contexte de construction Docker. L'absence d'un Dockerfile dans ce dossier génère une erreur.
• example/database : Une image Docker est construite en utilisant le sous-répertoire backend dans le dossier parent du fichier Compose. Le fichier backend.Dockerfile est utilisé pour définir les étapes de construction, ce fichier est recherché relativement au chemin de contexte, ce qui signifie que .. se résout vers le dossier parent du fichier Compose, donc backend.Dockerfile est un fichier frère.
• Une image Docker est construite en utilisant le répertoire custom avec le $HOME de l'utilisateur comme contexte Docker. Compose affiche un avertissement concernant le chemin non portable utilisé pour construire l'image.

Lors du push, les images Docker example/webapp et example/database sont poussées vers le registre par défaut. L'image du service custom est ignorée car aucun attribut image n'est défini et Compose affiche un avertissement concernant cet attribut manquant.

Attributs

La sous-section build définit les options de configuration qui sont appliquées par Compose pour construire les images Docker depuis la source. build peut être spécifié soit comme une chaîne contenant un chemin vers le contexte de construction, soit comme une structure détaillée :

En utilisant la syntaxe de chaîne, seul le contexte de construction peut être configuré comme soit :

• Un chemin relatif vers le dossier parent du fichier Compose. Ce chemin doit être un répertoire et doit contenir un Dockerfile

  services:
    webapp:
      build: ./dir

• Une URL de dépôt Git. Les URLs Git acceptent la configuration de contexte dans leur section fragment, séparée par deux points (:). La première partie représente la référence que Git vérifie, et peut être soit une branche, une étiquette, ou une référence distante. La seconde partie représente un sous-répertoire à l'intérieur du dépôt qui est utilisé comme contexte de construction.

  services:
    webapp:
      build: https://github.com/mycompany/example.git#branch_or_tag:subdirectory

Alternativement, build peut être un objet avec des champs définis comme suit :

additional_contexts

additional_contexts définit une liste de contextes nommés que le constructeur d'image devrait utiliser pendant la construction d'image.

additional_contexts peut être un mappage ou une liste :

build:
  context: .
  additional_contexts:
    - resources=/path/to/resources
    - app=docker-image://my-app:latest
    - source=https://github.com/myuser/project.git

build:
  context: .
  additional_contexts:
    resources: /path/to/resources
    app: docker-image://my-app:latest
    source: https://github.com/myuser/project.git

Quand utilisé comme une liste, la syntaxe suit le format NOM=VALEUR, où VALEUR est une chaîne. La validation au-delà de cela est la responsabilité du constructeur d'image (et est spécifique au constructeur). Compose supporte au moins les chemins absolus et relatifs vers un répertoire et les URLs de dépôt Git, comme context le fait. D'autres saveurs de contexte doivent être préfixées pour éviter l'ambiguïté avec un préfixe type://.

Compose vous avertit si le constructeur d'image ne supporte pas les contextes additionnels et peut lister les contextes inutilisés.

Des exemples illustratifs de comment cela est utilisé dans Buildx peuvent être trouvés ici.

additional_contexts peut aussi faire référence à une image construite par un autre service. Cela permet à une image de service d'être construite en utilisant une autre image de service comme image de base, et de partager des couches entre les images de service.

services:
 base:
  build:
    context: .
    dockerfile_inline: |
      FROM alpine
      RUN ...
 my-service:
  build:
    context: .
    dockerfile_inline: |
      FROM base # image construite pour le service base
      RUN ...
    additional_contexts:
      base: service:base

args

args définit les arguments de construction, c'est-à-dire les valeurs ARG du Dockerfile.

En utilisant le Dockerfile suivant comme exemple :

ARG GIT_COMMIT
RUN echo "Basé sur le commit : $GIT_COMMIT"

args peut être défini dans le fichier Compose sous la clé build pour définir GIT_COMMIT. args peut être défini comme un mappage ou une liste :

build:
  context: .
  args:
    GIT_COMMIT: cdc3b19

build:
  context: .
  args:
    - GIT_COMMIT=cdc3b19

Les valeurs peuvent être omises lors de la spécification d'un argument de construction, auquel cas sa valeur au moment de la construction doit être obtenue par l'interaction utilisateur, sinon l'argument de construction ne sera pas défini lors de la construction de l'image Docker.

args:
  - GIT_COMMIT

context

context définit soit un chemin vers un répertoire contenant un Dockerfile, soit une URL vers un dépôt Git.

Quand la valeur fournie est un chemin relatif, elle est interprétée comme relative au répertoire du projet. Compose vous avertit du chemin absolu utilisé pour définir le contexte de construction car ceux-ci empêchent le fichier Compose d'être portable.

build:
  context: ./dir

services:
  webapp:
    build: https://github.com/mycompany/webapp.git

Si non défini explicitement, context prend par défaut le répertoire du projet (.).

cache_from

cache_from définit une liste de sources que le constructeur d'image devrait utiliser pour la résolution de cache.

La syntaxe d'emplacement de cache suit le format global [NOM|type=TYPE[,CLÉ=VALEUR]]. Un simple NOM est en fait un raccourci de notation pour type=registry,ref=NOM.

Les implémentations Compose Build peuvent supporter des types personnalisés, la Spécification Compose définit des types canoniques qui doivent être supportés :

• registry pour récupérer le cache de construction depuis un ensemble d'images OCI défini par la clé ref

build:
  context: .
  cache_from:
    - alpine:latest
    - type=local,src=path/to/cache
    - type=gha

Les caches non supportés sont ignorés et n'empêchent pas de construire des images.

cache_to

cache_to définit une liste d'emplacements d'exportation à utiliser pour partager le cache de construction avec les constructions futures.

build:
  context: .
  cache_to:
   - user/app:cache
   - type=local,dest=path/to/cache

La cible de cache est définie en utilisant la même syntaxe type=TYPE[,CLÉ=VALEUR] définie par cache_from.

Les caches non supportés sont ignorés et n'empêchent pas de construire des images.

dockerfile

dockerfile définit un Dockerfile alternatif. Un chemin relatif est résolu depuis le contexte de construction. Compose vous avertit du chemin absolu utilisé pour définir le Dockerfile car il empêche les fichiers Compose d'être portables.

Quand défini, l'attribut dockerfile_inline n'est pas autorisé et Compose rejette tout fichier Compose ayant les deux définis.

build:
  context: .
  dockerfile: webapp.Dockerfile

dockerfile_inline

dockerfile_inline définit le contenu du Dockerfile comme une chaîne en ligne dans un fichier Compose. Quand défini, l'attribut dockerfile n'est pas autorisé et Compose rejette tout fichier Compose ayant les deux définis.

L'utilisation de la syntaxe de chaîne multi-ligne YAML est recommandée pour définir le contenu du Dockerfile :

build:
  context: .
  dockerfile_inline: |
    FROM baseimage
    RUN some command

entitlements

entitlements définit des droits privilégiés supplémentaires à permettre pendant la construction.

entitlements:
  - network.host
  - security.insecure

extra_hosts

extra_hosts ajoute des mappages de nom d'hôte au moment de la construction. Utilise la même syntaxe que extra_hosts.

extra_hosts:
  - "somehost=162.242.195.82"
  - "otherhost=50.31.209.229"
  - "myhostv6=::1"

Les adresses IPv6 peuvent être entourées de crochets, par exemple :

extra_hosts:
  - "myhostv6=[::1]"

Le séparateur = est préféré, mais : peut aussi être utilisé. Introduit dans Docker Compose version 2.24.1. Par exemple :

extra_hosts:
  - "somehost:162.242.195.82"
  - "myhostv6:::1"

Compose crée une entrée correspondante avec l'adresse IP et le nom d'hôte dans la configuration réseau du conteneur, ce qui signifie que pour Linux /etc/hosts obtiendra des lignes supplémentaires :

162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6

isolation

isolation spécifie la technologie d'isolation de conteneur d'une construction. Comme isolation, les valeurs supportées sont spécifiques à la plateforme.

labels

labels ajoute des métadonnées à l'image résultante. labels peut être défini soit comme un tableau soit comme une carte.

Il est recommandé d'utiliser la notation DNS inversée pour empêcher vos étiquettes d'entrer en conflit avec d'autres logiciels.

build:
  context: .
  labels:
    com.example.description: "Application web comptable"
    com.example.department: "Finance"
    com.example.label-with-empty-value: ""

build:
  context: .
  labels:
    - "com.example.description=Application web comptable"
    - "com.example.department=Finance"
    - "com.example.label-with-empty-value"

network

Définit le réseau auquel les conteneurs se connectent pour les instructions RUN pendant la construction.

build:
  context: .
  network: host

build:
  context: .
  network: custom_network_1

Utilise none pour désactiver le réseau pendant la construction :

build:
  context: .
  network: none

no_cache

no_cache désactive le cache du constructeur d'image et force une reconstruction complète depuis la source pour toutes les couches d'image. Cela s'applique seulement aux couches déclarées dans le Dockerfile, les images référencées peuvent être récupérées depuis le magasin d'images local chaque fois que l'étiquette a été mise à jour sur le registre (voir pull).

platforms

platforms définit une liste de plateformes cibles.

build:
  context: "."
  platforms:
    - "linux/amd64"
    - "linux/arm64"

Quand l'attribut platforms est omis, Compose inclut la plateforme du service dans la liste des plateformes cibles de construction par défaut.

Quand l'attribut platforms est défini, Compose inclut la plateforme du service, sinon les utilisateurs ne pourront pas exécuter les images qu'ils ont construites.

Compose signale une erreur dans les cas suivants :

• Quand la liste contient plusieurs plateformes mais l'implémentation est incapable de stocker des images multi-plateformes.

• Quand la liste contient une plateforme non supportée.

  build:
    context: "."
    platforms:
      - "linux/amd64"
      - "unsupported/unsupported"

• Quand la liste n'est pas vide et ne contient pas la plateforme du service.

  services:
    frontend:
      platform: "linux/amd64"
      build:
        context: "."
        platforms:
          - "linux/arm64"

privileged

privileged configure l'image de service à construire avec des privilèges élevés. Le support et les impacts réels sont spécifiques à la plateforme.

build:
  context: .
  privileged: true

pull

pull exige que le constructeur d'image tire les images référencées (directive FROM du Dockerfile), même si celles-ci sont déjà disponibles dans le magasin d'images local.

secrets

secrets donne accès aux données sensibles définies par secrets sur une base par service de construction. Deux variantes de syntaxe différentes sont supportées : la syntaxe courte et la syntaxe longue.

Compose signale une erreur si le secret n'est pas défini dans la section secrets de ce fichier Compose.

Syntaxe courte

La variante de syntaxe courte spécifie seulement le nom du secret. Cela donne au conteneur l'accès au secret et le monte en lecture seule à /run/secrets/<nom_secret> dans le conteneur. Le nom source et le point de montage de destination sont tous deux définis au nom du secret.

L'exemple suivant utilise la syntaxe courte pour donner à la construction du service frontend l'accès au secret server-certificate. La valeur de server-certificate est définie au contenu du fichier ./server.cert.

services:
  frontend:
    build:
      context: .
      secrets:
        - server-certificate
secrets:
  server-certificate:
    file: ./server.cert

Syntaxe longue

La syntaxe longue fournit plus de granularité dans la façon dont le secret est créé dans les conteneurs du service.

• source : Le nom du secret tel qu'il existe sur la plateforme.
• target : L'ID du secret tel que déclaré dans le Dockerfile. Par défaut à source si non spécifié.
• uid et gid : L'uid ou gid numérique qui possède le fichier dans /run/secrets/ dans les conteneurs de tâche du service. La valeur par défaut est USER.
• mode : Les permissions pour le fichier à monter dans /run/secrets/ dans les conteneurs de tâche du service, en notation octale. La valeur par défaut est les permissions lisibles par le monde (mode 0444). Le bit d'écriture doit être ignoré s'il est défini. Le bit exécutable peut être défini.

L'exemple suivant définit le nom du fichier secret server-certificate à server.crt dans le conteneur, définit le mode à 0440 (lisible par le groupe) et définit l'utilisateur et le groupe à 103. La valeur du secret server-certificate est fournie par la plateforme via une recherche et le cycle de vie du secret n'est pas directement géré par Compose.

services:
  frontend:
    build:
      context: .
      secrets:
        - source: server-certificate
          target: cert # ID secret dans le Dockerfile
          uid: "103"
          gid: "103"
          mode: 0440
secrets:
  server-certificate:
    external: true

# Dockerfile
FROM nginx
RUN --mount=type=secret,id=cert,required=true,target=/root/cert ...

Les constructions de service peuvent avoir accès à plusieurs secrets. Les syntaxes longue et courte pour les secrets peuvent être utilisées dans le même fichier Compose. Définir un secret dans la section secrets de niveau supérieur ne doit pas impliquer d'accorder l'accès à une construction de service à celui-ci. Un tel accès doit être explicite dans la spécification de service comme élément de service secrets.

ssh

ssh définit les authentifications SSH que le constructeur d'image devrait utiliser pendant la construction d'image (par exemple, clonage de dépôt privé).

La syntaxe de propriété ssh peut être soit :

• default : Laisser le constructeur se connecter à l'agent SSH.
• ID=path : Une définition clé/valeur d'un ID et du chemin associé. Cela peut être soit un fichier PEM, soit un chemin vers la socket de l'agent ssh.

build:
  context: .
  ssh:
    - default   # monte l'agent SSH par défaut

ou

build:
  context: .
  ssh: ["default"]   # monte l'agent SSH par défaut

Utilisant un id personnalisé myproject avec un chemin vers une clé SSH locale :

build:
  context: .
  ssh:
    - myproject=~/.ssh/myproject.pem

Le constructeur d'image peut alors s'appuyer sur cela pour monter la clé SSH pendant la construction.

Pour illustration, les montages SSH peuvent être utilisés pour monter la clé SSH définie par ID et accéder à une ressource sécurisée :

RUN --mount=type=ssh,id=myproject git clone ...

shm_size

shm_size définit la taille de la mémoire partagée (partition /dev/shm sur Linux) allouée pour construire les images Docker. Spécifier comme une valeur entière représentant le nombre d'octets ou comme une chaîne exprimant une valeur d'octet.

build:
  context: .
  shm_size: '2gb'

build:
  context: .
  shm_size: 10000000

tags

tags définit une liste de mappages d'étiquettes qui doivent être associés à l'image de construction. Cette liste vient en plus de la propriété image définie dans la section service

tags:
  - "myimage:mytag"
  - "registry/username/myrepos:my-other-tag"

target

target définit l'étape à construire comme définie dans un Dockerfile multi-étapes.

build:
  context: .
  target: prod

ulimits

ulimits remplace les ulimits par défaut pour un conteneur. Il est spécifié soit comme un entier pour une limite unique, soit comme un mappage pour les limites douces/dures.

services:
  frontend:
    build:
      context: .
      ulimits:
        nproc: 65535
        nofile:
          soft: 20000
          hard: 40000