Conceptos 04 - Configuración con variables de entorno

Concepto 1 de 7

La imagen no debe contener configuración de ambiente

Una imagen bien diseñada es un artefacto inmutable. La misma imagen debe poder ejecutarse en desarrollo, pruebas y producción.

Imagen (inmutable)

Código de la aplicación, dependencias, runtime. No cambia entre ambientes.

Configuración (variable)

Credenciales, URLs, puertos, niveles de log. Se inyecta en tiempo de ejecución mediante variables de entorno.

Cambie de ambiente y observe qué permanece igual y qué cambia.

Imagen · inmutable

miapp:1.4.0sha256:3f9a…c21e

Código, dependencias y runtime. Es el mismo artefacto en todos los ambientes.

Configuración · Desarrollo

DATABASE_URL: postgresql://app:••••@db:5432/midb
LOG_LEVEL: debug
PORT: 8000

Ambiente Desarrollo: misma imagen sha256:3f9a…c21e, configuración propia.

Concepto 2 de 7

Directiva environment en compose.yml

Define variables de entorno directamente en el archivo Compose, en formato NOMBRE=VALOR.

services:
  app:
    environment:
      - DATABASE_URL=postgresql://app:secreto@db:5432/midb
      - LOG_LEVEL=debug
      - PORT=8000

Cada variable se establece como NOMBRE=VALOR y queda disponible para el proceso dentro del contenedor.

Concepto 3 de 7

Archivo .env para interpolación

Compose lee automáticamente un archivo .env en el mismo directorio. Las variables se referencian con ${VARIABLE}.

POSTGRES_USER=app
POSTGRES_PASSWORD=secreto123
POSTGRES_DB=midb
APP_PORT=8000

services:
  app:
    ports:
      - "${APP_PORT}:8000"
    environment:
      - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}

  db:
    image: postgres:16
    environment:
      - POSTGRES_USER=${POSTGRES_USER}
      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
      - POSTGRES_DB=${POSTGRES_DB}

Edite los valores del .env y observe cómo Compose sustituye cada referencia en el archivo.

.envPOSTGRES_USER=POSTGRES_PASSWORD=POSTGRES_DB=APP_PORT=

Cambie un valor o bórrelo para ver el efecto.

docker compose config (resultado)

Concepto 4 de 7

Directiva env_file por servicio

Carga variables de entorno desde un archivo específico directamente en el contenedor, sin interpolación en compose.yml.

services:
  app:
    env_file:
      - ./app.env
  db:
    env_file:
      - ./db.env

Cada servicio puede tener su propio archivo de variables, manteniendo la configuración segmentada por componente.

Concepto 5 de 7

Diferencia entre .env y env_file

Dos mecanismos con propósitos y momentos de aplicación distintos.

.env

Interpolación en compose.yml

Las variables se sustituyen dentro del archivo Compose durante su procesamiento. Resuelve ${VARIABLE} antes de crear los contenedores.

Qué hace: Sustituye ${VARIABLE} dentro del archivo Compose
Cuándo actúa: Durante el procesamiento de compose.yml, antes de crear los contenedores
Alcance: Todo el archivo Compose

env_file

Inyección directa al contenedor

Las variables se cargan directamente en el entorno del contenedor. No participan en la sustitución de variables del archivo Compose.

Qué hace: Carga variables en el entorno del contenedor
Cuándo actúa: Al crear el contenedor del servicio que lo declara
Alcance: Solo el servicio que lo referencia

Concepto 6 de 7

Verificar variables de entorno en un contenedor

Confirmar que las variables se cargaron correctamente dentro del contenedor en ejecución.

Verificar variables 3 comandos

Ver todas las variables del servicio.

$ docker compose exec app envDATABASE_URL=postgresql://app:secreto123@db:5432/midbLOG_LEVEL=debugPORT=8000

Buscar una variable específica.

$ docker compose exec app env | grep DATABASE_URLDATABASE_URL=postgresql://app:secreto123@db:5432/midb

Ver la configuración resuelta de Compose.

$ docker compose config

Muestra la configuración con todas las variables ya resueltas. Es el primer paso para diagnosticar problemas de interpolación.

Concepto 7 de 7

Precedencia de variables de entorno

Cuando una misma variable se define en múltiples fuentes, Compose resuelve el valor siguiendo un orden de prioridad.

Línea de comandos. Variables pasadas con docker compose run -e.
Sustitución desde shell o .env. Variables en environment o env_file cuyo valor proviene de interpolación.
environment en compose.yml. Variables definidas directamente con valor fijo.
Archivos env_file. Variables cargadas desde archivos referenciados con env_file.

La lista va de mayor a menor prioridad. Active las fuentes que definen LOG_LEVEL y observe cuál gana. Por debajo de todas está el valor que la imagen define con ENV en su Dockerfile.

Autoevaluación

Comprueba lo que aprendiste

Cinco preguntas rápidas para verificar las ideas clave de la lectura. Cada respuesta incluye una explicación.