Entornos y variables en Docker Compose

Lo que cubriremos en este artículo

• Cómo Docker Compose utiliza las variables de entorno.
• Diferencias entre env_file, environment y .env.
• Cómo usar perfiles para servicios opcionales.
• Archivos override para desarrollo local.
• Gestión de múltiples entornos con Compose.

Introducción: entornos y variables en Docker Compose

Docker Compose facilita el lanzamiento simultáneo de varios contenedores. Sin embargo, cuando el mismo archivo Compose debe ejecutarse en diferentes entornos, necesitamos una forma limpia de adaptar la configuración. Las variables de entorno, los archivos env, los perfiles de Compose y los archivos override ayudan a mantener todo organizado. Esto evita duplicar la configuración varias veces.

En este artículo aprenderemos a trabajar de forma flexible con entornos y variables en Docker Compose.

Conceptos clave

• .env: Archivo estándar para variables de Compose.
• env_file: Archivo con variables para un servicio.
• environment: Variables directas en el servicio.
• Sustitución de variables: ${VAR} en archivos Compose.
• Perfiles: Grupos opcionales de servicios.
• Override: Archivo adicional que extiende la Compose base.
• Valor por defecto: Valor si falta la variable.
• Variable de shell: Variable del entorno de shell.

.env en el proyecto

Un archivo .env en el mismo directorio que compose.yaml rellena las variables:

APP_PORT=3000
DB_NAME=meine_db
DB_PASSWORD=geheim

En compose.yaml:

services:
  app:
    image: app:latest
    ports:
      - "${APP_PORT}:3000"
    environment:
      DB_NAME: ${DB_NAME}
      DB_PASSWORD: ${DB_PASSWORD}

Valores por defecto

ports:
  - "${APP_PORT:-3000}:3000"

Si APP_PORT no está definido, se utilizará 3000.

env_file por servicio

services:
  db:
    image: postgres:16
    env_file:
      - db.env

El archivo db.env contiene variables solo para este servicio.

environment directo

services:
  app:
    image: app
    environment:
      - NODE_ENV=production
      - LOG_LEVEL=info

Las combinaciones son posibles, pero rápidamente se vuelven confusas.

Perfiles de Compose

Los perfiles permiten iniciar servicios de forma opcional:

services:
  web:
    image: nginx
    profiles:
      - web
  monitoring:
    image: prometheus
    profiles:
      - monitoring

Para iniciar:

docker compose --profile monitoring up -d

Múltiples archivos Compose

docker compose -f compose.yaml -f compose.prod.yaml up -d

compose.prod.yaml sobrescribe o amplía la configuración.

Archivos override

Docker Compose carga automáticamente compose.override.yaml si existe:

# compose.override.yaml (local)
services:
  app:
    volumes:
      - ./src:/app/src
    environment:
      - DEBUG=1

De esta forma, las adaptaciones de desarrollo se mantienen fuera del archivo de producción.

Diferentes entornos

.
├── compose.yaml
├── compose.dev.yaml
├── compose.prod.yaml
├── .env.dev
└── .env.prod

Para iniciar:

docker compose -f compose.yaml -f compose.prod.yaml --env-file .env.prod up -d

Consejos

• Nunca incluyas archivos .env en Git.
• Separa claramente los archivos locales de los de producción.
• Usa valores por defecto para evitar errores.
• Gestiona los secrets mejor en Docker Swarm o bóvedas externas.
• Asigna nombres consistentes a las variables.
• Usa perfiles para herramientas opcionales.

Problemas comunes

• .env no se carga: El archivo debe estar en el directorio actual.
• Variables no definidas: La sustitución falla.
• Formato YAML incorrecto: Confundir environment con env_file.
• Secrets en .env: Riesgo de seguridad.
• Override se carga automáticamente: Configuración inesperada.
• Espacios en blanco en valores: Por ejemplo, en environment no debes añadir espacios alrededor de =.

Enlaces y referencias útiles

• BotServ.de Docker Compose
• BotServ.de Docker Secrets
• BotServ.de dotenvx
• BotServ.de Docker Befehle

FAQ: entornos de Compose

¿Cuál es la diferencia entre .env y env_file? .env define variables para el propio Compose, mientras que env_file pasa variables al contenedor.

¿Puedo usar múltiples archivos .env? Sí, con --env-file.

¿Se cargan automáticamente los archivos override? Sí, compose.override.yaml se carga automáticamente.

¿Qué son los perfiles de Compose? Grupos opcionales de servicios que se inician solo cuando sea necesario.

¿Debo usar environment en compose.yaml? Solo para valores no confidenciales. Nunca almacenes secrets allí.

Fuentes y lecturas relacionadas

• Compose Env: https://docs.docker.com/compose/environment-variables/
• Compose Profiles: https://docs.docker.com/compose/profiles/
• Multiple Compose Files: https://docs.docker.com/compose/multiple-compose-files/

Resumen: entornos y variables en Docker Compose

Docker Compose ofrece muchas formas de controlar la configuración a través de variables y archivos. .env es ideal para variables de Compose, env_file para entornos de servicios, los perfiles para servicios opcionales y los archivos override para adaptaciones locales. Si separas correctamente y no incluyes secrets en el control de versiones, podrás gestionar múltiples entornos de forma elegante con una base común.