El compose.yaml de Aurora Libros funciona, pero tiene la contraseña de PostgreSQL escrita en claro, la versión de la imagen fijada a mano y el puerto 8080 incrustado. Así no sirve para más de un entorno ni puede subirse a un repositorio compartido.

Este es el tema donde más gente se pierde, y por una razón concreta: hay dos sistemas distintos que se parecen y no tienen nada que ver. Uno actúa sobre el fichero YAML antes de arrancar nada; el otro define lo que ve el proceso dentro del contenedor. Sepáralos desde la primera línea y todo lo demás encaja.

1. Los dos sistemas, separados desde el principio
2. Sistema A: sustitución de variables en el YAML
3. De dónde saca Compose los valores para sustituir
4. Sistema B: variables dentro del contenedor
5. La tabla de precedencia completa
6. El fichero .env del proyecto
7. Aurora Libros parametrizada: .env y .env.example
8. Gestión de secretos: environment no es un sitio para contraseñas
9. Depuración con docker compose config

La confusión clásica: alguien escribe DB_PASSWORD=secreta en el .env y cree que la aplicación la verá. No la verá. El .env alimenta la sustitución; para que llegue al contenedor hace falta, además, un environment: { DB_PASSWORD: ${DB_PASSWORD} } o un env_file.

Cualquier ${VARIABLE} o $VARIABLE en el fichero se sustituye antes de que Docker vea nada. Sirve en cualquier posición: nombres de imagen, puertos, rutas, límites.

Usa siempre las llaves, ${VAR}: sin ellas, $VARIABLE_larga puede recortarse de forma inesperada al tocar un carácter no alfanumérico.

Los modificadores son la parte que de verdad marca la diferencia entre un fichero frágil y uno robusto:

Los dos puntos significan "trata el valor vacío igual que el ausente". En la práctica: :- para lo que tenga un valor por defecto sensato y :? para lo que no puede faltar.

Un error inmediato y con instrucciones, en lugar de una base de datos que arranca con contraseña vacía. Esa es la diferencia entre ${VAR} y ${VAR:?...}, y merece la pena aplicarla a todas las credenciales.

Cuando necesites un $ literal —muy habitual en command de shell o en patrones de nginx— duplícalo:

Un solo $ lo consume Compose; $$ produce un $ literal en la salida. Si ves errores del tipo Invalid interpolation format, casi siempre es un $ sin escapar.

Para resolver un ${VAR}, Compose busca en este orden, y el primero que encuentre gana:

Que el shell gane al .env es deliberado y muy práctico: permite a un pipeline de CI sobrescribir la versión de la imagen sin tocar ningún fichero.

Forma de mapa (recomendada: se lee mejor y se fusiona bien entre ficheros de override):

Forma de lista, con una capacidad que la de mapa no tiene:

Esa última línea es el pass-through: si HTTP_PROXY existe en tu shell, se pasa al contenedor con su valor; si no existe, la variable no se define. Útil para proxies corporativos y credenciales temporales que no quieres escribir en ningún fichero.

env_file carga variables desde ficheros, en el orden dado y ganando el último:

Sintaxis de un fichero .env/env_file: una CLAVE=valor por línea, # para comentarios, sin espacios alrededor del =, sin export, y las comillas se conservan como parte del valor salvo que envuelvan toda la cadena. DB_PASSWORD="secreta" y DB_PASSWORD=secreta dan el mismo resultado; DB_PASSWORD=se creta también funciona, porque no hace falta entrecomillar los espacios.

Cuando una misma variable aparece en varios sitios, este es el orden que decide qué ve el proceso, de mayor a menor prioridad:

Y una precisión que evita horas perdidas: el .env del proyecto no aparece en esta tabla. No inyecta nada en los contenedores; solo alimenta la sustitución del sistema A. Si quieres que una variable del .env llegue al proceso, tienes que pasarla explícitamente.

Es un fichero llamado exactamente .env, situado en el directorio del proyecto (el del compose.yaml, o el que indiques con --project-directory). Compose lo carga automáticamente y lo usa solo para la interpolación.

Fíjate en la última línea: en el .env también puedes fijar las variables de configuración de la propia CLI —COMPOSE_PROJECT_NAME, COMPOSE_FILE, COMPOSE_PROFILES—, que afectan al comportamiento de Compose y no a los contenedores.

Con --env-file puedes usar otro fichero, o varios:

Aplica el sistema A a las tres cosas que cambian entre entornos: versión de la imagen, puertos publicados y credenciales.

Ahora, la pieza cultural que convierte esto en algo usable por un equipo: el .env no se versiona, pero su plantilla sí.

El .env real no aparece: está ignorado. Con esto, quien clona el repositorio ejecuta cp .env.example .env, escribe su contraseña y levanta la plataforma. Y si se olvida, no obtiene un fallo críptico, sino el mensaje de ${DB_PASSWORD:?...} diciéndole exactamente qué hacer.

Todo lo anterior parametriza bien, pero no protege nada. Una contraseña en environment es visible para cualquiera que tenga acceso al demonio Docker:

Tres vías distintas, la misma contraseña en claro. Y hay más: las variables de entorno acaban en los volcados de estado del contenedor, se heredan a todos los procesos hijos (incluida cualquier dependencia de terceros que decida enviarlas en un informe de errores) y se cuelan en los registros de auditoría.

La alternativa de Compose es el bloque secrets:, que monta cada secreto como un fichero dentro de /run/secrets/:

Las imágenes oficiales de PostgreSQL, MySQL y muchas otras soportan el sufijo _FILE en sus variables: si defines POSTGRES_PASSWORD_FILE, el entrypoint lee la contraseña del fichero y nunca la expone como variable de entorno. Para tu propio código, el patrón es de tres líneas:

El secreto ha desaparecido del entorno y vive en un fichero con permisos restringidos, montado en un tmpfs que no toca el disco del contenedor y no queda en ninguna capa de la imagen.

Aviso importante. Lo anterior es el mecanismo básico de Compose y es adecuado para desarrollo local y despliegues pequeños en un solo host, con datos ficticios como los de este curso. El manejo de credenciales reales —rotación, control de acceso, auditoría, cifrado en reposo— debe validarse siempre con el responsable de seguridad de tu organización, que decidirá qué gestor de secretos corresponde. Nada de lo que hagas con ficheros locales sustituye a esa conversación. El endurecimiento general de contenedores se trata en la lección 05-03.

Cuando una variable no llega donde esperas, no adivines:

Comparar config con config --no-interpolate te dice al instante si el problema está en la sustitución (sistema A) o en el paso al contenedor (sistema B). Y docker compose exec <servicio> env te da la verdad definitiva: lo que el proceso ve de verdad.

Cuidado: la salida de config contiene los secretos resueltos en claro. Nunca la vuelques en un log de CI ni la pegues en un ticket.

Creer que el .env llega a los contenedores. No llega. Solo alimenta la interpolación. Necesitas environment o env_file además.

Usar ${VAR} sin :? para valores obligatorios. Una contraseña ausente se convierte en cadena vacía y arrancas una base de datos sin contraseña, en silencio.

Subir el .env a Git. Es el escape de credenciales más frecuente que existe. Ignóralo desde el primer commit y versiona .env.example.

Olvidar el $$ para un $ literal. Provoca Invalid interpolation format o, peor, una cadena vacía donde esperabas un patrón.

Usar echo para crear el fichero de un secreto. Añade un salto de línea final que forma parte de la contraseña. Usa printf o recorta con .trim().

Poner comillas en el .env esperando que se ignoren. En algunos casos forman parte del valor; ante la duda, verifica con docker compose config.

Consejo: una regla de oro para decidir dónde va cada cosa. ¿Cambia entre entornos y no es sensible? Interpolación con ${VAR:-defecto}. ¿Es sensible? secrets:. ¿Es estructural y no cambia nunca, como DB_HOST: aurora-db? Escríbelo directamente en el compose.yaml.

Ejercicio 1. Parametriza el puerto de la web con ${WEB_PUERTO:-8080} y demuestra las cuatro fuentes de valor con su precedencia: sin nada definido, con .env, con una variable exportada en el shell y con una variable en la propia línea de comandos. Usa docker compose config para verificar cada caso sin levantar nada.

Ejercicio 2. Define en el compose.yaml NODE_ENV: ${NODE_ENV:-production} y, además, un env_file que contenga NODE_ENV=desde-fichero. Predice qué valor verá el proceso, verifícalo, y explica el resultado con la tabla de precedencia.

Ejercicio 3. Convierte la contraseña de PostgreSQL en un secreto de fichero para aurora-db y aurora-api, y demuestra con tres comandos distintos que ya no aparece en el entorno de ninguno de los dos contenedores.

Solución 1.

La escala completa en cuatro comandos: defecto < .env < shell exportado < línea de comandos. Que el shell gane al .env es lo que permite a un pipeline de CI cambiar la versión de la imagen sin tocar ficheros, y lo que a la vez explica un desconcierto muy común: si tienes una variable vieja exportada en tu sesión, el .env no la sobrescribe. Limpia con unset antes de sospechar del fichero.

Solución 2. El proceso verá production.

En la tabla de precedencia, environment (nivel 3) está por encima de env_file (nivel 5). El fichero solo aporta las variables que el bloque environment no define, así que sirve como base y environment como sobreescritura puntual. Y ojo con el ${NODE_ENV:-production}: si además exportas NODE_ENV=development en tu shell, la interpolación lo resuelve a development y el resultado cambia, aunque el nivel de precedencia siga siendo el 3.

Solución 3.

Con el ajuste de server.js del apartado 8 para leer DB_PASSWORD_FILE, la verificación:

Las tres vías muestran la ruta, nunca el valor, y los nueve libros confirman que la conexión sigue funcionando. Un detalle esencial: si cambias esto sobre una base de datos ya inicializada, la contraseña no se actualiza, porque POSTGRES_PASSWORD* solo se aplica en la primera inicialización del volumen. En un entorno de pruebas, docker compose down -v; en uno real, un ALTER USER.

Tienes separados los dos sistemas que causan casi toda la confusión con Compose. El sistema A es la sustitución ${VAR} que Compose hace sobre el YAML antes de crear nada, con sus modificadores :- y - para valores por defecto y :? y ? para valores obligatorios que abortan con un mensaje útil, el escape $$ para el dólar literal, y su orden de búsqueda: línea de comandos, shell exportado, --env-file y .env del proyecto. El sistema B es lo que ve el proceso: environment en forma de mapa o de lista —con el pass-through de una clave sin valor— y env_file con su required: false.

Conoces la tabla de precedencia completa, de run -e hasta el ENV del Dockerfile, y la trampa que encierra: el .env del proyecto no está en esa tabla, porque no inyecta nada en los contenedores. Aurora Libros queda parametrizada en versión de imagen, puertos y credenciales, con un .env local ignorado por Git y un .env.example versionado que documenta qué hace falta para arrancar.

Y sabes que environment no es sitio para una contraseña: la has visto en claro por tres vías distintas, y la has retirado con el bloque secrets:, que monta ficheros en /run/secrets/ y encaja con el patrón _FILE de las imágenes oficiales y con tres líneas de tu propio código. Con el aviso que no debes olvidar: para credenciales reales, valida siempre el enfoque con el responsable de seguridad de tu organización.

En la lección siguiente, Perfiles, Overrides y Múltiples Entornos, harás que un mismo proyecto sirva para desarrollo, pruebas y producción sin duplicar ficheros: perfiles para levantar bajo demanda herramientas como Adminer o un servicio de semillas, el compose.override.yaml automático y la combinación explícita con varios -f junto a sus reglas de fusión, extends e include: para compartir definiciones entre equipos, y la convención de nombres de proyecto que permite que las pilas de dos entornos convivan en la misma máquina.