Variables de entorno en Docker Compose

Las variables de entorno en Docker Compose son valores externos que parametrizan el archivo YAML sin tener que editarlo cada vez.

En el artículo anterior escribimos un docker-compose.yml que funcionaba, pero tenía un problema de seguridad y flexibilidad.

Teníamos cosas como:

environment:
  MYSQL_ROOT_PASSWORD: password123  # ❌ ¡Contraseña visible!
ports:
  - "8080:80"                       # ❌ Puerto fijo

Si compartes este proyecto:

1. Seguridad: Todo el mundo conoce tu contraseña de administrador.
2. Rigidez: Si tu compañero ya usa el puerto 8080 para otra cosa, tiene que editar tu archivo docker-compose.yml para poder trabajar.

Para solucionar esto, Docker Compose se integra nativamente con archivos .env.

Transformando nuestro YAML

Vamos a arreglar nuestro desastre de seguridad. En lugar de escribir los valores a fuego, ponemos “placeholders” (marcadores de posición):

services:
  db:
    image: mysql:5.7
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_PASSWORD}  # ✅ Variable
      MYSQL_DATABASE: ${DB_NAME}           # ✅ Variable

  admin:
    image: phpmyadmin/phpmyadmin
    ports:
      - "${HOST_PORT}:80"                  # ✅ Variable
    depends_on:
      - db

Si intentas ejecutar docker compose up ahora, Docker te avisará (o usará cadenas vacías) porque esas variables no están definidas. Necesitamos darles valor.

El archivo .env

Docker Compose busca automáticamente en la misma carpeta un archivo llamado .env (oculto, empieza por punto).

Es un archivo de texto simple con formato CLAVE=VALOR. Crea un archivo .env junto a tu docker-compose.yml:

# Configuración de Base de Datos
DB_PASSWORD=SuperSecreto123!
DB_NAME=mi_aplicacion

# Configuración de Puertos
HOST_PORT=8080

ports:
  - "${PORT:-3000}:80"

Seguridad y Git

El archivo .env NUNCA se sube al repositorio de código (Git). Contiene tus secretos reales. Tu contraseña de producción, tus claves de API, etc.

Entonces, ¿cómo sabe mi equipo qué variables necesita crear? La práctica estándar es crear un archivo de plantilla llamado .env.example (o .env.template).

Pasos para hacerlo bien:

# .env.example
DB_PASSWORD=cambiar_esto
DB_NAME=app_db
HOST_PORT=8080

Cuando un desarrollador nuevo se descargue tu proyecto, verá el .example, hará una copia, la renombrará a .env y pondrá sus propios valores.

Secrets en Docker Compose

Si tenéis una contraseña, un token o una clave privada, lo ideal es no tratarlo como una variable normal.

Para estos casos, Docker Compose permite declarar secrets. La idea es sencilla: en lugar de pasar el valor como variable de entorno, Docker monta un archivo dentro del contenedor y la aplicación lo lee desde ahí.

Por ejemplo, para una base de datos PostgreSQL:

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_USER: admin
      POSTGRES_PASSWORD_FILE: /run/secrets/db_password
    secrets:
      - db_password

secrets:
  db_password:
    file: ./secrets/db_password.txt

En este caso, la contraseña real está en un archivo local:

./secrets/db_password.txt

Y dentro del contenedor aparece montada como:

/run/secrets/db_password

La imagen oficial de PostgreSQL entiende la variable POSTGRES_PASSWORD_FILE, lee la contraseña desde ese archivo y evita que tengamos que escribirla directamente en el YAML.

La diferencia entre .env y env_file

Hay una confusión común en Docker Compose.

1. Sustitución en YAML (lo que acabamos de ver): Docker lee el .env y cambia ${VAR} dentro del propio archivo docker-compose.yml. Sirve para configurar puertos, réplicas, versiones de imagen, etc.
2. Pasar variables al contenedor (env_file): A veces tienes una aplicación (ej: Django o Laravel) que necesita 50 variables de entorno para funcionar internamente. Escribirlas todas en la sección environment: del YAML ensucia mucho. Puedes decirle a Docker: “Coge este archivo entero e inyecta todas sus variables DENTRO del contenedor”.

services:
  mi-app:
    image: mi-imagen
    env_file:
      - ./config/app.env  # Carga todo lo que haya aquí dentro del contenedor