Docker Build-Args en Compose

Qué cubre este artículo sobre Build-Args en Compose

• Diferencia entre args y environment.
• Pasar argumentos de build a Dockerfiles.
• Uso en builds de múltiples etapas.
• Consejos para valores sensibles.
• Evitar errores comunes.

Introducción: Docker Build-Args en Compose

Al construir imágenes propias con Docker Compose, frecuentemente necesitas pasar información al Dockerfile durante la compilación. Esto puede incluir versiones, arquitecturas, URLs de repositorio o flags. En Docker Compose esto se hace con build.args. Las variables de entorno en tiempo de ejecución, por otro lado, se establecen con environment. Confundir ambas puede causar fallos en la compilación o dejar datos sensibles dentro de la imagen.

Este artículo te muestra cómo usar correctamente Build-Args en Compose.

Términos clave

• Build-Arg: Variable disponible durante la compilación de la imagen.
• ENV: Variable en el contenedor en ejecución.
• ARG: Instrucción de Dockerfile para argumentos de build.
• .env: Archivo para variables de Compose.
• Multi-Stage: Build en múltiples etapas.
• Cache: Caché de capas de build.
• Secret: Valor secreto, no incluido en la imagen.

args vs. environment

services:
  app:
    build:
      context: .
      args:
        APP_VERSION: "1.2.3"
    environment:
      NODE_ENV: production

APP_VERSION está disponible durante la compilación. NODE_ENV solo en tiempo de ejecución.

Dockerfile con ARG

ARG APP_VERSION=1.0.0
FROM node:20

ENV APP_VERSION=${APP_VERSION}

RUN echo "Baue Version ${APP_VERSION}"

WORKDIR /app
COPY . .
RUN npm install
CMD ["node", "index.js"]

Usar archivo .env

.env:

APP_VERSION=1.2.3
BUILD_TARGET=production

services:
  app:
    build:
      context: .
      args:
        APP_VERSION: ${APP_VERSION}
        BUILD_TARGET: ${BUILD_TARGET}

En el archivo Compose

services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        - APP_VERSION
        - BUILD_TARGET=production

Si solo se especifica el nombre, Compose toma el valor del entorno.

Build-Args y caché

Los argumentos de build forman parte de la clave de caché. Si un ARG cambia, la capa correspondiente se reconstruye:

ARG APP_VERSION
FROM base

Define APP_VERSION lo más tarde posible para que las capas anteriores permanezcan en caché.

Multi-Stage con ARG

ARG BUILD_TARGET=production

FROM node:20 AS builder
WORKDIR /app
COPY package*.json .
RUN npm install
COPY . .
RUN npm run build

FROM node:20-alpine
COPY --from=builder /app/dist /app
CMD ["node", "/app/index.js"]

services:
  app:
    build:
      context: .
      args:
        BUILD_TARGET: production

Datos sensibles

Los argumentos de build no aparecen en el contenedor en ejecución, pero pueden ser visibles en las capas de la imagen:

docker history mein-image

Para secretos, usa docker buildx build --secret o BuildKit-Secrets en Compose:

services:
  app:
    build:
      context: .
      secrets:
        - npm_token

secrets:
  npm_token:
    file: ./npm_token.txt

Consejos

• ARG solo para tiempo de compilación, ENV para tiempo de ejecución.
• No pases valores sensibles como ARG.
• Define ARGs tarde en el Dockerfile para preservar el caché.
• Centraliza valores en .env.
• Define valores por defecto en el Dockerfile.
• Documenta qué argumentos necesita una imagen.

Errores típicos

• ARG no se encuentra en el contenedor: Solo ENV u otras formas de paso son visibles.
• Valores en la imagen: Los ARGs pueden ser visibles en el historial.
• Orden incorrecto: Cambiar un ARG invalida el caché.
• .env no cargado: El archivo está en el directorio equivocado.
• Composición faltante: Usa solo args en el build de Compose.
• Datos sensibles en Build-Args: Problema de seguridad.

Enlaces e información adicional

• BotServ.de Docker Compose
• BotServ.de Docker Multi-Stage Builds
• BotServ.de Docker Image-Optimización
• BotServ.de Docker Secrets

FAQ: Docker Build-Args en Compose

¿Cuál es la diferencia entre args y environment? args para la compilación, environment para la ejecución.

¿Están los Build-Args visibles en el contenedor? No directamente, a menos que se transfieran a ENV.

¿Puedo cargar Build-Args desde .env? Sí, a través de ${VARIABLE} en docker-compose.yml.

¿Debería establecer Secrets como Build-Args? No, es mejor usar BuildKit-Secrets.

¿Qué pasa si falta un ARG? Si el Dockerfile tiene un valor por defecto, se usa ese.

Fuentes y lecturas adicionales

• Dockerfile ARG: https://docs.docker.com/engine/reference/builder/#arg
• Compose Build: https://docs.docker.com/compose/compose-file/build/
• BuildKit Secrets: https://docs.docker.com/build/building/secrets/

Resumen: Docker Build-Args en Compose

Los Build-Args permiten pasar información al Dockerfile sin dejarla en el contenedor en ejecución. En Docker Compose se establecen a través de build.args y se reciben en el Dockerfile con ARG. Las variables de entorno, en cambio, sirven para la ejecución. Para eficiencia de caché y seguridad, define los Build-Args tarde, trata valores sensibles como BuildKit-Secrets y establece valores por defecto en el Dockerfile. Quien separa limpiamente args y environment evita errores de compilación y seguridad comunes.