Configura variables de entorno predefinidas en Docker Compose

Docker Compose incluye varias variables de entorno predefinidas. También hereda variables de entorno comunes de la CLI de Docker, como DOCKER_HOST y DOCKER_CONTEXT. Consulta la referencia de variables de entorno de la CLI de Docker para más detalles.

Esta página explica cómo establecer o cambiar las siguientes variables de entorno predefinidas:

• COMPOSE_PROJECT_NAME
• COMPOSE_FILE
• COMPOSE_PROFILES
• COMPOSE_CONVERT_WINDOWS_PATHS
• COMPOSE_PATH_SEPARATOR
• COMPOSE_IGNORE_ORPHANS
• COMPOSE_REMOVE_ORPHANS
• COMPOSE_PARALLEL_LIMIT
• COMPOSE_ANSI
• COMPOSE_STATUS_STDOUT
• COMPOSE_ENV_FILES
• COMPOSE_DISABLE_ENV_FILE
• COMPOSE_MENU
• COMPOSE_EXPERIMENTAL
• COMPOSE_PROGRESS

Métodos para sobrescribir

Al cambiar o establecer variables de entorno, ten en cuenta la precedencia de las variables de entorno.

Detalles de configuración

Configuración de proyectos y archivos

COMPOSE_PROJECT_NAME

Establece el nombre del proyecto. Este valor se antepone junto con el nombre del servicio al nombre del contenedor al iniciarse.

Por ejemplo, si el nombre de tu proyecto es myapp e incluye dos servicios, db y web, Compose iniciará contenedores llamados myapp-db-1 y myapp-web-1 respectivamente.

Compose puede establecer el nombre del proyecto de diferentes maneras. El nivel de precedencia (de mayor a menor) para cada método es el siguiente:

1. La bandera de línea de comandos -p
2. COMPOSE_PROJECT_NAME
3. La variable de nivel superior name: del archivo de configuración (o el último name: de una serie de archivos de configuración especificados mediante -f)
4. El nombre base (basename) del directorio del proyecto que contiene el archivo de configuración (o que contiene el primer archivo de configuración especificado mediante -f)
5. El nombre base (basename) del directorio actual si no se especifica ningún archivo de configuración

Los nombres de los proyectos deben contener únicamente letras minúsculas, dígitos decimales, guiones y guiones bajos, y deben comenzar con una letra minúscula o un dígito decimal. Si el nombre base (basename) del directorio del proyecto o del directorio actual no cumple con esta restricción, debes utilizar uno de los otros mecanismos.

Consulta también usar -p para especificar un nombre de proyecto.

COMPOSE_FILE

Especifica la ruta a un archivo de Compose. Se admite la especificación de múltiples archivos de Compose.

• Comportamiento por defecto: Si no se proporciona, Compose busca un archivo llamado compose.yaml en el directorio actual y, si no lo encuentra, busca de forma recursiva en cada directorio padre hasta encontrar un archivo con ese nombre.
• Al especificar múltiples archivos de Compose, los separadores de ruta por defecto son:

  • Mac y Linux: : (dos puntos)

  • Windows: ; (punto y coma) Por ejemplo:

    COMPOSE_FILE=compose.yaml:compose.prod.yaml
    

    El separador de ruta también se puede personalizar utilizando COMPOSE_PATH_SEPARATOR.

Consulta también usar -f para especificar el nombre y la ruta de uno o más archivos de Compose.

COMPOSE_PROFILES

Especifica uno o más perfiles que se habilitarán al ejecutar docker compose up.

Se inician los servicios con perfiles coincidentes, así como cualquier servicio para el cual no se haya definido ningún perfil.

Por ejemplo, llamar a docker compose up con COMPOSE_PROFILES=frontend selecciona los servicios con el perfil frontend así como los servicios sin un perfil especificado.

Si especificas múltiples perfiles, utiliza una coma como separador.

El siguiente ejemplo habilita todos los servicios que coinciden con los perfiles frontend y debug, así como los servicios sin perfil.

COMPOSE_PROFILES=frontend,debug

Consulta también Usar perfiles con Compose y la opción de línea de comandos --profile.

COMPOSE_PATH_SEPARATOR

Especifica un separador de ruta diferente para los elementos enumerados en COMPOSE_FILE.

• Por defecto es:
  • En macOS y Linux: :
  • En Windows: ;

COMPOSE_ENV_FILES

Especifica qué archivos de entorno debe utilizar Compose si no se usa --env-file.

Al usar múltiples archivos de entorno, utiliza una coma como separador. Por ejemplo:

COMPOSE_ENV_FILES=.env.envfile1,.env.envfile2

Si COMPOSE_ENV_FILES no está configurada y no proporcionas --env-file en la CLI, Docker Compose utiliza el comportamiento por defecto, que consiste en buscar un archivo .env en el directorio del proyecto.

COMPOSE_DISABLE_ENV_FILE

Permite desactivar el uso del archivo .env por defecto.

• Valores admitidos:
  • true o 1: Compose ignora el archivo .env
  • false o 0: Compose busca un archivo .env en el directorio del proyecto
• Por defecto es: 0

Gestión de entornos y ciclo de vida de los contenedores

COMPOSE_CONVERT_WINDOWS_PATHS

Cuando está habilitada, Compose realiza la conversión de rutas del estilo de Windows al estilo de Unix en las definiciones de volúmenes.

• Valores admitidos:
  • true o 1: para habilitar
  • false o 0: para deshabilitar
• Por defecto es: 0

COMPOSE_IGNORE_ORPHANS

Cuando está habilitada, Compose no intenta detectar contenedores huérfanos para el proyecto.

• Valores admitidos:
  • true o 1: para habilitar
  • false o 0: para deshabilitar
• Por defecto es: 0

COMPOSE_REMOVE_ORPHANS

Cuando está habilitada, Compose elimina automáticamente los contenedores huérfanos al actualizar un servicio o stack. Los contenedores huérfanos son aquellos creados por una configuración anterior pero que ya no están definidos en el archivo compose.yaml actual.

• Valores admitidos:
  • true o 1: para habilitar la eliminación automática de contenedores huérfanos
  • false o 0: para deshabilitar la eliminación automática. En su lugar, Compose muestra una advertencia sobre los contenedores huérfanos.
• Por defecto es: 0

COMPOSE_PARALLEL_LIMIT

Especifica el nivel máximo de paralelismo para llamadas concurrentes al motor (engine).

Salida (Output)

COMPOSE_ANSI

Especifica cuándo imprimir caracteres de control ANSI.

• Valores admitidos:
  • auto: Compose detecta si se puede usar el modo TTY. De lo contrario, utiliza el modo de texto plano
  • never: utiliza el modo de texto plano
  • always o 0: utiliza el modo TTY
• Por defecto es: auto

COMPOSE_STATUS_STDOUT

Cuando está habilitada, Compose escribe su estado interno y mensajes de progreso en stdout en lugar de stderr. El valor por defecto es false para separar claramente los flujos de salida entre los mensajes de Compose y los registros (logs) de tu contenedor.

• Valores admitidos:
  • true o 1: para habilitar
  • false o 0: para deshabilitar
• Por defecto es: 0

COMPOSE_PROGRESS

Defines el tipo de salida del progreso, si no se usa --progress.

Los valores admitidos son auto, tty, plain, json y quiet. El valor por defecto es auto.

Experiencia de usuario

COMPOSE_MENU

Cuando está habilitada, Compose muestra un menú de navegación donde puedes elegir abrir el stack de Compose en Docker Desktop, activar el modo watch (observación) o usar Docker Debug.

• Valores admitidos:
  • true o 1: para habilitar
  • false o 0: para deshabilitar
• Por defecto es: 1 si obtuviste Docker Compose a través de Docker Desktop; de lo contrario, el valor por defecto es 0

COMPOSE_EXPERIMENTAL

Esta es una variable opcional de exclusión (opt-out). Cuando está desactivada, desactiva las funciones experimentales.

• Valores admitidos:
  • true o 1: para habilitar
  • false o 0: para deshabilitar
• Por defecto es: 1

No soportadas en Compose V2

Las siguientes variables de entorno no tienen efecto en Compose V2.

• COMPOSE_API_VERSION Por defecto, la versión de la API se negocia con el servidor. Utiliza DOCKER_API_VERSION.
  Consulta la página de referencia de variables de entorno de la CLI de Docker.
• COMPOSE_HTTP_TIMEOUT
• COMPOSE_TLS_VERSION
• COMPOSE_FORCE_WINDOWS_HOST
• COMPOSE_INTERACTIVE_NO_CLI
• COMPOSE_DOCKER_CLI_BUILD Utiliza DOCKER_BUILDKIT para seleccionar entre BuildKit y el constructor clásico. Si DOCKER_BUILDKIT=0, docker compose build utiliza el constructor clásico para compilar las imágenes.