Docker Compose Environment Variables

Variables de entorno

Las variables de entorno permiten parametrizar el comportamiento de los servicios en Docker Compose sin modificar el código de las aplicaciones. Estas variables se inyectan en los contenedores durante la ejecución y son fundamentales para crear aplicaciones configurables y adaptables a diferentes entornos.

Docker Compose ofrece dos mecanismos principales para definir variables de entorno en los servicios: la clave environment y la directiva env_file. Ambos enfoques tienen características específicas que los hacen útiles en diferentes escenarios.

Definición con environment

La clave environment permite declarar variables directamente en el archivo compose.yaml. Esta aproximación es ideal cuando necesitas definir pocas variables o cuando quieres mantener la configuración visible en el propio archivo de Compose.

services:
  web:
    image: nginx:1.25
    environment:
      - NODE_ENV=production
      - API_URL=https://api.example.com
      - DEBUG=false

También puedes usar la sintaxis de mapeo para mayor claridad:

services:
  database:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: secretpassword
      MYSQL_DATABASE: myapp
      MYSQL_USER: appuser
      MYSQL_PASSWORD: userpass

Definición con env_file

La directiva env_file permite cargar variables desde archivos externos, manteniendo la configuración separada del archivo de Compose. Esto es especialmente útil para gestionar múltiples entornos o cuando tienes muchas variables de configuración.

services:
  app:
    image: node:20
    env_file:
      - .env
      - .env.local

El contenido del archivo .env seguiría este formato:

NODE_ENV=development
PORT=3000
DATABASE_URL=postgresql://user:pass@localhost/db
API_KEY=abc123xyz

Puedes especificar múltiples archivos y Docker Compose los procesará en orden. Si existe la misma variable en varios archivos, el último archivo tiene precedencia.

Diferencias entre environment y env_file

La elección entre environment y env_file depende de tus necesidades específicas:

• environment es perfecto para variables críticas del servicio que deben estar visibles en el archivo de Compose
• env_file es ideal para configuraciones extensas, credenciales sensibles o cuando necesitas compartir variables entre múltiples servicios

services:
  api:
    image: python:3.13
    environment:
      # Variables críticas del servicio
      - FLASK_ENV=production
      - WORKERS=4
    env_file:
      # Configuración extensa desde archivo
      - .env.production

Precedencia de variables

Cuando usas ambos mecanismos, Docker Compose aplica el siguiente orden de precedencia:

• 1. Variables definidas en environment (mayor prioridad)
• 2. Variables cargadas desde env_file
• 3. Variables del sistema anfitrión

services:
  service:
    image: alpine:latest
    environment:
      - DEBUG=true  # Esta prevalece sobre la del archivo
    env_file:
      - .env  # Contiene DEBUG=false

Casos de uso prácticos

Las variables de entorno son especialmente útiles para configurar bases de datos:

services:
  postgres:
    image: postgres:16
    environment:
      POSTGRES_DB: ecommerce
      POSTGRES_USER: shop_user
      POSTGRES_PASSWORD: secure_password
    
  redis:
    image: redis:7
    environment:
      REDIS_APPENDONLY: "yes"
      REDIS_MAXMEMORY: "256mb"

Para aplicaciones web, puedes configurar diferentes modos de ejecución:

services:
  frontend:
    image: node:20
    environment:
      NODE_ENV: development
      VITE_API_BASE_URL: http://localhost:8000
      VITE_ENABLE_ANALYTICS: "false"

Las variables también permiten personalizar el comportamiento de herramientas y frameworks:

services:
  java-app:
    image: openjdk:21
    environment:
      JAVA_OPTS: "-Xmx512m -Xms256m"
      SPRING_PROFILES_ACTIVE: docker
      LOGGING_LEVEL_ROOT: INFO

Esta flexibilidad hace que las variables de entorno sean una herramienta esencial para crear aplicaciones containerizadas que se adapten fácilmente a diferentes contextos de despliegue sin requerir cambios en el código fuente.

Archivos .env y sustitución

Archivos .env por proyecto

Docker Compose busca automáticamente un archivo .env en el directorio raíz del proyecto, junto al archivo compose.yaml. Este archivo especial se carga sin necesidad de declararlo explícitamente con la directiva env_file, proporcionando un mecanismo conveniente para definir variables de configuración del proyecto.

El archivo .env del proyecto tiene una función dual: define variables que pueden usarse tanto para sustitución en el archivo compose.yaml como variables de entorno que se pasan a los servicios.

# .env (archivo en la raíz del proyecto)
COMPOSE_PROJECT_NAME=mi-aplicacion
DB_VERSION=postgres:16
APP_PORT=3000
ENVIRONMENT=development

Con este archivo, puedes referenciar las variables directamente en el compose.yaml:

services:
  database:
    image: ${DB_VERSION}
    ports:
      - "${APP_PORT}:5432"
    
  app:
    build: .
    environment:
      - NODE_ENV=${ENVIRONMENT}

Sustitución de variables con ${VAR}

La sustitución de variables permite hacer dinámicos los valores en el archivo compose.yaml utilizando la sintaxis ${VARIABLE}. Esta funcionalidad es fundamental para crear archivos de Compose reutilizables entre diferentes entornos.

services:
  web:
    image: nginx:${NGINX_VERSION}
    ports:
      - "${WEB_PORT:-80}:80"
    volumes:
      - "${DATA_PATH}/html:/usr/share/nginx/html"
    environment:
      - SERVER_NAME=${DOMAIN_NAME}

Docker Compose resuelve estas variables antes de crear los servicios, permitiendo personalizar completamente la configuración sin modificar el archivo compose.yaml.

Valores por defecto

Puedes especificar valores por defecto para las variables usando la sintaxis ${VARIABLE:-default}. Si la variable no está definida o está vacía, Docker Compose utilizará el valor por defecto especificado.

services:
  redis:
    image: redis:${REDIS_VERSION:-7}
    command: redis-server --maxmemory ${REDIS_MEMORY:-128mb}
    ports:
      - "${REDIS_PORT:-6379}:6379"

También existe la sintaxis ${VARIABLE-default} que solo aplica el valor por defecto si la variable no está definida, pero respeta valores vacíos:

services:
  app:
    image: python:${PYTHON_VERSION-3.13}
    environment:
      - DEBUG=${DEBUG-false}
      - LOG_LEVEL=${LOG_LEVEL:-info}  # Se aplica si está vacía o no definida
      - API_KEY=${API_KEY-}           # Solo se aplica si no está definida

Ejemplo práctico con múltiples entornos

Esta funcionalidad es especialmente útil para gestionar múltiples entornos. Puedes tener diferentes archivos .env para cada entorno:

.env.development:

DB_HOST=localhost
DB_PORT=5432
APP_DEBUG=true
REPLICAS=1
NGINX_VERSION=1.25-alpine

.env.production:

DB_HOST=prod-database.company.com
DB_PORT=5432
APP_DEBUG=false
REPLICAS=3
NGINX_VERSION=1.25

El archivo compose.yaml permanece igual, usando sustitución:

services:
  app:
    build: .
    environment:
      - DEBUG=${APP_DEBUG:-false}
      - DATABASE_HOST=${DB_HOST}
      - DATABASE_PORT=${DB_PORT:-5432}
    deploy:
      replicas: ${REPLICAS:-1}
  
  nginx:
    image: nginx:${NGINX_VERSION:-latest}
    ports:
      - "${HTTP_PORT:-80}:80"

Para usar un archivo específico, simplemente renómbralo o cópialo como .env:

# Para desarrollo
cp .env.development .env
docker compose up

# Para producción  
cp .env.production .env
docker compose up -d

Validación y errores

Docker Compose genera errores si una variable requerida no está definida y no tiene valor por defecto:

services:
  database:
    image: postgres:16
    environment:
      # Error si API_SECRET no está definida
      - DATABASE_PASSWORD=${API_SECRET}
      # OK, usa "changeme" por defecto
      - FALLBACK_PASSWORD=${BACKUP_SECRET:-changeme}

Esta validación ayuda a detectar configuraciones incompletas antes de que los servicios fallen durante la ejecución, mejorando la robustez del despliegue.

Escapado de variables

Si necesitas usar el símbolo $ literalmente en lugar de para sustitución, puedes escaparlo duplicándolo:

services:
  app:
    environment:
      - LITERAL_DOLLAR=$$HOME  # Se convierte en $HOME literal
      - SUBSTITUTION=${HOME}   # Se sustituye por el valor de HOME

Esta funcionalidad de sustitución convierte Docker Compose en una herramienta flexible para gestionar configuraciones complejas manteniendo un solo archivo de definición de servicios que se adapta automáticamente a diferentes contextos de despliegue.