La guía práctica de variables de entorno en proyectos Docker

La configuración fuera del código

Cuando trabajas con Docker, una de las primeras cosas que aprendes es a desacoplar la configuración del código. Las variables de entorno son la herramienta fundamental para conseguirlo. Permiten que el mismo contenedor Docker funcione en diferentes entornos —desarrollo, staging, producción— sin recompilar ni modificar la imagen.

Si tu aplicación necesita saber una clave de API, la URL de una base de datos o un puerto específico, esa información nunca debería estar hardcodeada. Mi regla es clara: todo lo que puede cambiar entre entornos o es sensible, va fuera del código.

Uso de variables de entorno en Docker y Docker Compose

La forma más básica de pasar variables de entorno a un contenedor Docker es con el flag -e en el comando docker run. Para un solo contenedor, esto funciona.

docker run -e DB_HOST=mi_base_de_datos -e DB_PORT=5432 mi_imagen_app

Cuando trabajas con múltiples servicios y Docker Compose, la gestión se vuelve más estructurada. Puedes definir las variables directamente en tu docker-compose.yml o, lo que es más habitual, en un archivo .env en la raíz de tu proyecto.

Gestión de la configuración con archivos .env

El archivo .env es el estándar de facto para definir variables de entorno en entornos de desarrollo. Docker Compose lo lee automáticamente si está en la misma carpeta que tu docker-compose.yml.

Un ejemplo de docker-compose.yml usando un .env:

version: '3.8'
services:
  app:
    image: mi_imagen_app
    environment:
      - DB_HOST=${DB_HOST}
      - DB_PORT=${DB_PORT}
    # ...

Y su correspondiente .env para desarrollo:

DB_HOST=localhost
DB_PORT=5432
API_KEY=clave_desarrollo_segura

Esto simplifica la configuración para el equipo de desarrollo. Cada desarrollador tiene su .env local y no expone credenciales sensibles en el control de versiones. Esto evita errores donde tu código funciona en local y falla en producción.

Variables de entorno vs. secretos

Aquí es donde muchos proyectos fallan en producción. Una variable de entorno es adecuada para configuración no sensible: puertos, flags, nombres de host. Un secreto es para información altamente sensible: contraseñas de bases de datos, claves de API, tokens de autenticación.

Las variables de entorno son visibles para cualquier proceso dentro del contenedor y pueden aparecer en logs si no tienes cuidado. Los secretos están diseñados para ser inyectados de forma segura, solo al proceso que los necesita, sin persistir en el sistema de archivos del contenedor ni en sus variables de entorno.

Docker tiene su propio sistema de Docker Secrets, pero para setups más sencillos o cuando no usas Docker Swarm, soluciones como HashiCorp Vault o simplemente inyectar secretos desde el orquestador (Kubernetes Secrets, variables de entorno cifradas en CI/CD) son más comunes. No trates la clave de Stripe igual que el puerto de Redis.

Ventajas y complejidades de la gestión de variables

Gestionar las variables de entorno correctamente no es gratis.

Ventajas:

Flexibilidad de despliegue: El mismo código base y la misma imagen Docker sirven para múltiples entornos.
Seguridad mejorada: Evitas hardcodear credenciales y puedes gestionarlas de forma centralizada.
Colaboración: Cada desarrollador puede tener su configuración local sin conflictos.

Complejidades:

Manejo de .env: Hay que educar al equipo para no subir .env a Git y gestionar .env.example.
Visibilidad: Las variables de entorno son fáciles de inspeccionar dentro del contenedor.
Coherencia: Asegurarse de que las variables necesarias estén siempre presentes en cada entorno.

Mi experiencia con clientes me ha demostrado que una buena gestión de la configuración es uno de los pilares de la estabilidad en producción. Si no tienes un método claro, acabarás parcheando .env o, peor, metiendo credenciales en el código.

Si buscas formas de gestionar configuraciones para distintos entornos sin duplicar código, tengo un artículo sobre cómo gestionar configuración por entorno sin duplicar código. Y si utilizas Docker Compose para tus proyectos, te interesará saber cómo usar Docker Compose profiles para entornos distintos y separar tus servicios.