# 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`](/reference/compose-file/build/services/#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.

```yaml
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`

  ```yml
  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.

  ```yml
  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:

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

```yml
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](#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`](https://github.com/docker/buildx/blob/master/docs/reference/buildx_build.md#-additional-build-contexts---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.

```yaml
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:

```Dockerfile
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:

```yml
build:
  context: .
  args:
    GIT_COMMIT: cdc3b19
```

```yml
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.

```yml
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`

```yml
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.

```yml
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`](#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.

```yml
build:
  context: ./dir
```

```yml
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.

```yml
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:

```yml
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.

```yaml
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`](/reference/compose-file/build/services/#extra_hosts).

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

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

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

Se prefiere el separador `=`, pero también se puede utilizar `:`. Introducido en Docker Compose versión [2.24.1](https://github.com/docker/compose/releases/tag/v2.24.1). Por ejemplo:

```yml
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:

```text
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](/reference/compose-file/build/services/#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.

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

```yml
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.

```yaml
build:
  context: .
  network: host
```

```yaml
build:
  context: .
  network: custom_network_1
```

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

```yaml
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](#pull)).

### `platforms`

`platforms` define una lista de plataformas de destino ([platforms](/reference/compose-file/build/services/#platform)).

```yml
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.

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

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

  ```yml
  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.

```yml
build:
  context: .
  privileged: true
```

### `provenance`




`provenance` configura el compilador para añadir una [atestación de procedencia (provenance)](https://slsa.dev/provenance/v0.2#schema) 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`.

```yaml
build:
  context: .
  provenance: true
```

```yaml
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)](https://slsa.dev/provenance/v0.2#schema) 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)

```yaml
build:
  context: .
  sbom: true
```

```yaml
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](/reference/compose-file/build/services/#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`](/reference/compose-file/build/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`.

```yml
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](https://wintelguy.com/permissions-calc.pl) 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.

```yml
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
# 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](/reference/compose-file/build/services/#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](https://en.wikipedia.org/wiki/Privacy-Enhanced_Mail) o la ruta al socket de ssh-agent.

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

o

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

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

```yaml
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](https://github.com/moby/buildkit/blob/master/frontend/dockerfile/docs/reference.md#run---mounttypessh) para montar la clave SSH establecida por ID y acceder a un recurso protegido:

```console
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](/reference/compose-file/build/extension/#specifying-byte-values).

```yml
build:
  context: .
  shm_size: "2gb"
```

```yaml
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](/reference/compose-file/build/services/#image).

```yml
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).

```yml
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).

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