Compartir comentarios
Las respuestas se generan en base a la documentación.

Precedencia de las variables de entorno en Docker Compose

Tabla de contenidos

Cuando una misma variable de entorno se establece en múltiples fuentes, Docker Compose sigue una regla de precedencia para determinar el valor de dicha variable en el entorno de tu contenedor.

Esta página explica cómo determina Docker Compose el valor final de una variable de entorno cuando está definida en múltiples ubicaciones.

El orden de precedencia (de mayor a menor) es el siguiente:

  1. Establecida utilizando docker compose run -e en la CLI.
  2. Establecida con el atributo environment o env_file pero con el valor interpolado desde tu shell o un archivo de entorno (ya sea tu archivo .env por defecto o con el argumento --env-file en la CLI).
  3. Establecida utilizando solo el atributo environment en el archivo de Compose.
  4. Uso del atributo env_file en el archivo de Compose.
  5. Establecida en una imagen de contenedor en la directiva ENV. Cualquier ajuste de ARG o ENV en un Dockerfile se evalúa únicamente si no existe una entrada de Docker Compose para environment, env_file o run --env.

Ejemplo sencillo

En el siguiente ejemplo, se establece un valor diferente para la misma variable de entorno en un archivo .env y con el atributo environment en el archivo de Compose:

$ cat ./webapp.env
NODE_ENV=test

$ cat compose.yaml
services:
  webapp:
    image: 'webapp'
    env_file:
     - ./webapp.env
    environment:
     - NODE_ENV=production

La variable de entorno definida con el atributo environment tiene precedencia.

$ docker compose run webapp env | grep NODE_ENV
NODE_ENV=production

Ejemplo avanzado

La siguiente tabla utiliza como ejemplo VALUE, una variable de entorno que define la versión de una imagen.

Cómo funciona la tabla

Cada columna representa un contexto desde el cual puedes establecer un valor o sustituir un valor para VALUE.

Las columnas Host OS environment (entorno del SO host) y archivo .env se enumeran únicamente con fines ilustrativos. En realidad, no producen una variable en el contenedor por sí solas, sino en conjunto con el atributo environment o env_file.

Cada fila representa una combinación de contextos donde se establece VALUE, se sustituye o ambos. La columna Resultado indica el valor final de VALUE en cada escenario.

#docker compose runAtributo environmentAtributo env_fileENV de la imagenEntorno del SO HostArchivo .envResultado
1----VALUE=1.4VALUE=1.3-
2--VALUE=1.6VALUE=1.5VALUE=1.4-VALUE=1.6
3-VALUE=1.7-VALUE=1.5VALUE=1.4-VALUE=1.7
4---VALUE=1.5VALUE=1.4VALUE=1.3VALUE=1.5
5--env VALUE=1.8--VALUE=1.5VALUE=1.4VALUE=1.3VALUE=1.8
6--env VALUE--VALUE=1.5VALUE=1.4VALUE=1.3VALUE=1.4
7--env VALUE--VALUE=1.5-VALUE=1.3VALUE=1.3
8--VALUEVALUE=1.5VALUE=1.4VALUE=1.3VALUE=1.4
9--VALUEVALUE=1.5-VALUE=1.3VALUE=1.3
10-VALUE-VALUE=1.5VALUE=1.4VALUE=1.3VALUE=1.4
11-VALUE-VALUE=1.5-VALUE=1.3VALUE=1.3
12--env VALUEVALUE=1.7-VALUE=1.5VALUE=1.4VALUE=1.3VALUE=1.4
13--env VALUE=1.8VALUE=1.7-VALUE=1.5VALUE=1.4VALUE=1.3VALUE=1.8
14--env VALUE=1.8-VALUE=1.6VALUE=1.5VALUE=1.4VALUE=1.3VALUE=1.8
15--env VALUE=1.8VALUE=1.7VALUE=1.6VALUE=1.5VALUE=1.4VALUE=1.3VALUE=1.8

Entendiendo los resultados de la precedencia

Resultado 1: El entorno local tiene precedencia, pero el archivo de Compose no está configurado para replicar esto dentro del contenedor, por lo que no se establece dicha variable.

Resultado 2: El atributo env_file en el archivo de Compose define un valor explícito para VALUE, por lo que el entorno del contenedor se establece en consecuencia.

Resultado 3: El atributo environment en el archivo de Compose define un valor explícito para VALUE, por lo que el entorno del contenedor se establece en consecuencia.

Resultado 4: La directiva ENV de la imagen declara la variable VALUE y, dado que el archivo de Compose no está configurado para sobrescribir este valor, esta variable queda definida por la imagen.

Resultado 5: El comando docker compose run tiene la bandera (flag) --env establecida con un valor explícito y sobrescribe el valor configurado por la imagen.

Resultado 6: El comando docker compose run tiene la bandera --env configurada para replicar el valor del entorno. El valor del SO Host tiene precedencia y se replica en el entorno del contenedor.

Resultado 7: El comando docker compose run tiene la bandera --env configurada para replicar el valor del entorno. Se selecciona el valor del archivo .env para definir el entorno del contenedor.

Resultado 8: El atributo env_file en el archivo de Compose está configurado para replicar VALUE desde el entorno local. El valor del SO Host tiene precedencia y se replica en el entorno del contenedor.

Resultado 9: El atributo env_file en el archivo de Compose está configurado para replicar VALUE desde el entorno local. Se selecciona el valor del archivo .env para definir el entorno del contenedor.

Resultado 10: El atributo environment en el archivo de Compose está configurado para replicar VALUE desde el entorno local. El valor del SO Host tiene precedencia y se replica en el entorno del contenedor.

Resultado 11: El atributo environment en el archivo de Compose está configurado para replicar VALUE desde el entorno local. Se selecciona el valor del archivo .env para definir el entorno del contenedor.

Resultado 12: La bandera --env tiene mayor precedencia que los atributos environment y env_file y está configurada para replicar VALUE desde el entorno local. El valor del SO Host tiene precedencia y se replica en el entorno del contenedor.

Resultados 13 a 15: La bandera --env tiene mayor precedencia que los atributos environment y env_file, por lo que establece el valor.

Siguientes pasos