Especificación de compilación de Compose

Build es una parte opcional de la especificación de Compose. Indica a Compose cómo (re)construir una aplicación a partir de su código fuente y te ayuda a definir el proceso de construcción dentro de un archivo de Compose de forma portable. Puedes especificar build como una única cadena que define una ruta de contexto, o como una definición de construcción detallada.

Cuando se especifica build como una cadena, toda la ruta se utiliza como un contexto de Docker para ejecutar una compilación de Docker, buscando un Dockerfile canónico en la raíz del directorio.

Cuando se especifica build como una estructura detallada, se pueden indicar argumentos de compilación (build arguments), incluida una ubicación alternativa del Dockerfile.

En ambos casos, la ruta puede ser absoluta o relativa. Si es relativa, se resuelve a partir del directorio que contiene tu archivo de Compose. Si es absoluta, la ruta impide que el archivo de Compose sea portable, por lo que Compose muestra una advertencia.

Uso de build e image

Cuando Compose se encuentra tanto con una subsección build para un servicio como con un atributo image, sigue las reglas definidas por el atributo pull_policy.

Si pull_policy no está presente en la definición del servicio, Compose intenta descargar (pull) la imagen primero y luego compila desde el código fuente si la imagen no se encuentra en el registro o en la caché de la plataforma.

Publicación de imágenes compiladas

Compose con soporte de build ofrece una opción para subir (push) las imágenes compiladas a un registro. Al hacerlo, no intenta subir las imágenes del servicio que no tengan un atributo image. Compose te advierte sobre la falta del atributo image, lo que impide que las imágenes se suban.

Ejemplo ilustrativo

El siguiente ejemplo ilustra los conceptos de la Especificación de Compilación de Compose (Compose Build Specification) con una aplicación de ejemplo concreta. El ejemplo no es normativo.

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

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

  custom:
    build: ~/custom

Cuando se utiliza para compilar imágenes de servicios a partir del código fuente, el archivo de Compose crea tres imágenes de Docker:

• example/webapp: Se compila una imagen de Docker utilizando el subdirectorio webapp, dentro de la carpeta del archivo de Compose, como el contexto de compilación de Docker. La falta de un Dockerfile en esta carpeta devuelve un error.
• example/database: Se compila una imagen de Docker utilizando el subdirectorio backend dentro de la carpeta del archivo de Compose. Se utiliza el archivo backend.Dockerfile para definir los pasos de compilación, este archivo se busca en relación con la ruta del contexto, lo que significa que .. se resuelve a la carpeta del archivo de Compose, por lo que backend.Dockerfile es un archivo hermano.
• Se compila una imagen de Docker utilizando el directorio custom con el $HOME del usuario como contexto de Docker. Compose muestra una advertencia sobre la ruta no portable utilizada para compilar la imagen.

Al subir (push), las imágenes de Docker example/webapp y example/database se suben al registro predeterminado. La imagen del servicio custom se omite ya que no tiene establecido ningún atributo image y Compose muestra una advertencia sobre la falta de este atributo.

Atributos

La subsección build define las opciones de configuración que Compose aplica para compilar imágenes de Docker a partir del código fuente. build se puede especificar como una cadena que contiene una ruta al contexto de compilación o como una estructura detallada:

Utilizando la sintaxis de cadena, solo se puede configurar el contexto de compilación como:

• Una ruta relativa a la carpeta del archivo de Compose. Esta ruta debe ser un directorio y debe contener un Dockerfile

  services:
    webapp:
      build: ./dir

• Una URL de repositorio Git. Las URL de Git admiten la configuración de contexto en su sección de fragmento, separada por dos puntos (:). La primera parte representa la referencia que Git descarga (checkout), y puede ser una rama, una etiqueta o una referencia remota. La segunda parte representa un subdirectorio dentro del repositorio que se utiliza como contexto de compilación.

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

Alternativamente, build puede ser un objeto con los campos definidos de la siguiente manera:

additional_contexts

additional_contexts define una lista de contextos con nombre que el compilador de imágenes debe usar durante la compilación de la imagen.

additional_contexts puede ser un mapeo o una lista:

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

Cuando se usa como una lista, la sintaxis sigue el formato NOMBRE=VALOR, donde VALOR es una cadena. La validación más allá de eso es responsabilidad del compilador de imágenes (y es específica del compilador). Compose admite al menos rutas absolutas y relativas a un directorio y URL de repositorios Git, al igual que lo hace context. Otras variantes de contexto deben llevar un prefijo para evitar ambigüedades con un prefijo type://.

Compose te advierte si el compilador de imágenes no admite contextos adicionales y puede enumerar los contextos no utilizados.

Consulta la documentación de referencia de docker buildx build --build-context para ver un ejemplo de uso.

additional_contexts también puede referirse a una imagen compilada por otro servicio. Esto permite compilar la imagen de un servicio utilizando la imagen de otro servicio como imagen base, y compartir capas entre las imágenes de los servicios.

services:
  base:
    build:
      context: .
      dockerfile_inline: |
        FROM alpine
        RUN ...
  my-service:
    build:
      context: .
      dockerfile_inline: |
        FROM base # imagen compilada para el servicio base
        RUN ...
      additional_contexts:
        base: service:base

args

args define argumentos de compilación (build arguments), es decir, valores ARG del Dockerfile.

Tomando el siguiente Dockerfile como ejemplo:

ARG GIT_COMMIT
RUN echo "Based on commit: $GIT_COMMIT"

Se puede configurar args en el archivo de Compose bajo la clave build para definir GIT_COMMIT. args se puede configurar como un mapeo o como una lista:

build:
  context: .
  args:
    GIT_COMMIT: cdc3b19

build:
  context: .
  args:
    - GIT_COMMIT=cdc3b19

Los valores se pueden omitir al especificar un argumento de compilación, en cuyo caso su valor en el momento de la compilación debe obtenerse mediante la interacción del usuario; de lo contrario, el argumento de compilación no se establecerá al compilar la imagen de Docker.

args:
  - GIT_COMMIT

cache_from

cache_from define una lista de fuentes que el compilador de imágenes debe utilizar para la resolución de la caché.

La sintaxis de la ubicación de la caché sigue el formato global [NOMBRE|type=TIPO[,CLAVE=VALOR]]. Un NOMBRE simple es en realidad una notación abreviada para type=registry,ref=NOMBRE.

Las implementaciones de Compose Build pueden admitir tipos personalizados, la Especificación de Compose define tipos canónicos que deben ser compatibles:

• registry para recuperar la caché de compilación de una imagen OCI establecida por la clave ref

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

Las cachés no compatibles se ignoran y no impiden compilar imágenes.

cache_to

cache_to define una lista de ubicaciones de exportación que se utilizarán para compartir la caché de compilación con futuras compilaciones.

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

El destino de la caché se define utilizando la misma sintaxis type=TIPO[,CLAVE=VALOR] definida por cache_from.

Las cachés no compatibles se ignoran y no impiden compilar imágenes.

context

context define una ruta a un directorio que contiene un Dockerfile, o una URL a un repositorio Git.

Cuando el valor proporcionado es una ruta relativa, se interpreta como relativa al directorio del proyecto. Compose te advierte sobre la ruta absoluta utilizada para definir el contexto de compilación, ya que estas impiden que el archivo de Compose sea portable.

build:
  context: ./dir

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

Si no se establece explícitamente, context tiene como valor predeterminado el directorio del proyecto (.).

dockerfile

dockerfile establece un Dockerfile alternativo. Una ruta relativa se resuelve a partir del contexto de compilación. Compose te advierte sobre la ruta absoluta utilizada para definir el Dockerfile, ya que impide que los archivos de Compose sean portables.

Cuando está configurado, el atributo dockerfile_inline no está permitido y Compose rechaza cualquier archivo de Compose que tenga ambos configurados.

build:
  context: .
  dockerfile: webapp.Dockerfile

dockerfile_inline

dockerfile_inline define el contenido del Dockerfile como una cadena integrada (inline) en un archivo de Compose. Cuando está configurado, el atributo dockerfile no está permitido y Compose rechaza cualquier archivo de Compose que tenga ambos configurados.

Se recomienda el uso de la sintaxis de cadena multilínea de YAML para definir el contenido del Dockerfile:

build:
  context: .
  dockerfile_inline: |
    FROM baseimage
    RUN algún comando

entitlements

entitlements define derechos de privilegios adicionales que se permitirán durante la compilación.

entitlements:
  - network.host
  - security.insecure

extra_hosts

extra_hosts añade asignaciones de nombres de host en el momento de la compilación. Usa la misma sintaxis que extra_hosts.

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

Las direcciones IPv6 se pueden encerrar entre corchetes, por ejemplo:

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

Se prefiere el separador =, pero también se puede utilizar :. Introducido en Docker Compose versión 2.24.1. Por ejemplo:

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

Compose crea la entrada correspondiente con la dirección IP y el nombre de host en la configuración de red del contenedor, lo que significa que para Linux /etc/hosts recibirá líneas adicionales:

162.242.195.82  somehost
50.31.209.229   otherhost
::1             myhostv6

isolation

isolation especifica la tecnología de aislamiento del contenedor de compilación. Al igual que isolation, los valores admitidos son específicos de la plataforma.

labels

labels añade metadatos a la imagen resultante. labels se puede configurar como un array o como un mapa.

Se recomienda utilizar la notación DNS inversa para evitar que tus etiquetas entren en conflicto con otro software.

build:
  context: .
  labels:
    com.example.description: "Aplicación web de contabilidad"
    com.example.department: "Finanzas"
    com.example.label-with-empty-value: ""

build:
  context: .
  labels:
    - "com.example.description=Aplicación web de contabilidad"
    - "com.example.department=Finanzas"
    - "com.example.label-with-empty-value"

network

Establece la red a la que se conectan los contenedores para las instrucciones RUN durante la compilación.

build:
  context: .
  network: host

build:
  context: .
  network: custom_network_1

Usa none para desactivar la red durante la compilación:

build:
  context: .
  network: none

no_cache

no_cache desactiva la caché del compilador de imágenes y obliga a una reconstrucción completa desde el origen para todas las capas de la imagen. Esto solo se aplica a las capas declaradas en el Dockerfile; las imágenes referenciadas se pueden recuperar del almacén de imágenes local cada vez que se haya actualizado la etiqueta en el registro (consulta pull).

platforms

platforms define una lista de plataformas de destino (platforms).

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

Cuando se omite el atributo platforms, Compose incluye la plataforma del servicio en la lista de plataformas de destino de compilación predeterminadas.

Cuando se define el atributo platforms, Compose incluye la plataforma del servicio; de lo contrario, los usuarios no podrán ejecutar las imágenes que compilaron.

Compose informa de un error en los siguientes casos:

• Cuando la lista contiene varias plataformas pero la implementación no puede almacenar imágenes multiplataforma.

• Cuando la lista contiene una plataforma no compatible.

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

• Cuando la lista no está vacía y no contiene la plataforma del servicio.

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

privileged

privileged configura la imagen del servicio para compilarse con privilegios elevados. El soporte y los impactos reales son específicos de la plataforma.

build:
  context: .
  privileged: true

provenance

provenance configura el compilador para añadir una atestación de procedencia (provenance) a la imagen publicada.

El valor puede ser un booleano para activar/desactivar la atestación de procedencia, o una cadena clave=valor para establecer la configuración de procedencia. Puedes utilizar esto para seleccionar el nivel de detalle que se incluirá en la atestación de procedencia configurando el parámetro mode.

build:
  context: .
  provenance: true

build:
  context: .
  provenance: mode=max

pull

pull requiere que el compilador de imágenes descargue (pull) las imágenes referenciadas (directiva FROM del Dockerfile), incluso si ya están disponibles en el almacén de imágenes local.

sbom

sbom configura el compilador para añadir una atestación de procedencia (provenance) a la imagen publicada. El valor puede ser un booleano para activar/desactivar la atestación de SBOM, o una cadena clave=valor para establecer la configuración del generador de SBOM. Esto te permite seleccionar una imagen alternativa del generador de SBOM (consulta https://github.com/moby/buildkit/blob/master/docs/attestations/sbom-protocol.md)

build:
  context: .
  sbom: true

build:
  context: .
  sbom: generator=docker/scout-sbom-indexer:latest # Usa un generador de SBOM alternativo

secrets

secrets concede acceso a datos confidenciales definidos por los secrets en función de la compilación de cada servicio. Se admiten dos variantes de sintaxis diferentes: la sintaxis corta y la sintaxis larga.

Compose informa de un error si el secreto no está definido en la sección secrets de este archivo de Compose.

Sintaxis corta

La variante de sintaxis corta solo especifica el nombre del secreto. Esto concede al contenedor acceso al secreto y lo monta como de solo lectura en /run/secrets/<nombre_del_secreto> dentro del contenedor. El nombre de origen y el punto de montaje de destino se establecen con el nombre del secreto.

El siguiente ejemplo utiliza la sintaxis corta para conceder a la compilación del servicio frontend acceso al secreto server-certificate. El valor de server-certificate se establece con el contenido del archivo ./server.cert.

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

Sintaxis larga

La sintaxis larga proporciona más granularidad en cómo se crea el secreto dentro de los contenedores del servicio.

• source: El nombre del secreto tal como existe en la plataforma.
• target: El ID del secreto tal como se declara en el Dockerfile. Por defecto es source si no se especifica.
• uid y gid: El uid o gid numérico que posee el archivo dentro de /run/secrets/ en los contenedores de tareas del servicio. El valor predeterminado es USER.
• mode: Los permisos para el archivo que se va a montar en /run/secrets/ en los contenedores de tareas del servicio, en notación octal. El valor predeterminado son permisos de lectura universal (modo 0444). El bit de escritura debe ignorarse si está configurado. El bit de ejecución se puede configurar.

El siguiente ejemplo establece el nombre del archivo de secreto server-certificate en server.crt dentro del contenedor, establece el modo en 0440 (lectura por grupo) y establece el usuario y el grupo en 103. La plataforma proporciona el valor del secreto server-certificate mediante una búsqueda y Compose no gestiona directamente el ciclo de vida del secreto.

services:
  frontend:
    build:
      context: .
      secrets:
        - source: server-certificate
          target: cert # ID del secreto en el 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 ...

A las compilaciones de servicios se les puede conceder acceso a múltiples secretos. Se pueden utilizar las sintaxis larga y corta para los secretos en el mismo archivo de Compose. La definición de un secreto en la sección de nivel superior secrets no debe implicar conceder acceso a la compilación de ningún servicio. Dicha concesión debe ser explícita dentro de la especificación del servicio como elemento del servicio secrets.

ssh

ssh define las autenticaciones SSH que el compilador de imágenes debe utilizar durante la compilación de la imagen (por ejemplo, clonar un repositorio privado).

La sintaxis de la propiedad ssh puede ser:

• default: Permite que el compilador se conecte al SSH-agent.
• ID=ruta: Una definición de clave/valor de un ID y la ruta asociada. Puede ser un archivo PEM o la ruta al socket de ssh-agent.

build:
  context: .
  ssh:
    - default # monta el agente SSH predeterminado

o

build:
  context: .
  ssh: ["default"] # monta el agente SSH predeterminado

Utilizando un id personalizado myproject con la ruta a una clave SSH local:

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

El compilador de imágenes puede confiar en esto para montar la clave SSH durante la compilación.

A modo de ilustración, se pueden utilizar los montajes SSH para montar la clave SSH establecida por ID y acceder a un recurso protegido:

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

shm_size

shm_size establece el tamaño de la memoria compartida (partición /dev/shm en Linux) asignada para compilar imágenes de Docker. Se especifica como un valor entero que representa la cantidad de bytes o como una cadena que expresa un valor de bytes.

build:
  context: .
  shm_size: "2gb"

build:
  context: .
  shm_size: 10000000

tags

tags define una lista de asignaciones de etiquetas que deben asociarse a la imagen compilada. Esta lista se añade a la propiedad image definida en la sección del servicio.

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

target

target define la etapa a compilar tal como se define dentro de un Dockerfile de múltiples etapas (multi-stage).

build:
  context: .
  target: prod

ulimits

ulimits invalida los ulimits predeterminados para un contenedor. Se especifica como un número entero para un límite único o como un mapeo para límites blandos/duros (soft/hard).

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