Cómo gestionar configuración por entorno sin duplicar código

Cada entorno de una aplicación —desarrollo, staging, producción— necesita su propia configuración. La base de datos, las claves de APIs externas, los puertos, todo cambia. El error más común que veo es intentar gestionar esto duplicando archivos de configuración o, peor aún, hardcodeando valores que luego hay que cambiar a mano antes de cada deploy. Esto introduce errores y hace que tu código funcione en local y falle en producción.

La forma de evitar estos problemas es adherirse al principio de la Twelve-Factor App que establece que la configuración debe almacenarse en el entorno, separada del código. Mi regla es: si cambia entre entornos, es configuración y no debe estar en el repositorio.

El problema de la configuración duplicada y los errores en producción

Cuando un proyecto crece, la gestión manual de la configuración se convierte en una pesadilla. Un desarrollador puede olvidar actualizar un parámetro en el entorno de staging, o un valor de una API de pruebas se cuela en producción. He visto equipos perder días depurando errores que eran simplemente una URL mal configurada o una clave API caducada.

Duplicar archivos como config.production.js y config.development.js dentro del repositorio no soluciona el problema. Sigue siendo fácil cometer errores, y no escala bien. Además, las credenciales o claves sensibles no deberían vivir en el control de versiones.

La filosofía Twelve-Factor: Configuración en el entorno

El principio III de las Twelve-Factor Apps es claro: “Configuración. Almacenar la configuración en el entorno”. Esto significa que todos los datos que varían entre despliegues —credenciales de bases de datos, claves de servicios externos, hostnames— deben ser inyectados en la aplicación a través de variables de entorno.

Una aplicación bien diseñada no necesita saber en qué entorno se ejecuta. Simplemente lee las variables que le proporciona el sistema operativo o el orquestador. Esto hace que tu código sea agnóstico al entorno, lo que facilita los despliegues y reduce la posibilidad de errores.

# Ejemplo de cómo se vería la configuración en el entorno
DATABASE_URL=postgresql://user:pass@host:port/database
API_KEY_STRIPE=sk_live_XXXXXXXXXXXXXXXXXXXX
NODE_ENV=production

Cómo implementar la gestión de variables de entorno en tu proyecto

Para desarrollo local, la forma más sencilla es usar un archivo .env y una librería como dotenv (en Node.js, por ejemplo). Este archivo no se versiona —se excluye con .gitignore— y cada desarrollador lo configura en su máquina. Para que el resto del equipo sepa qué variables necesita el proyecto, se mantiene un archivo .env.example versionado con valores de ejemplo o placeholders.

# .env.example
# Este archivo sí se sube al repositorio
DATABASE_URL=postgresql://localhost:5432/myapp_dev
API_KEY_STRIPE=sk_test_XXXXXXXXXXXXXXXXXXXX
PORT=3000

// En tu aplicación Node.js
require('dotenv').config(); // Carga las variables de .env
const dbUrl = process.env.DATABASE_URL;
const apiKey = process.env.API_KEY_STRIPE;

En producción o staging, las variables de entorno se inyectan directamente desde el orquestador (Docker Compose, Kubernetes) o el proveedor de hosting (Vercel, Netlify, DigitalOcean Apps). Esto garantiza que las credenciales sensibles nunca estén en tu repositorio y que cada entorno tenga su configuración específica de forma segura. Si usas Docker, puedes definir estas variables en tu docker-compose.yml o en el comando docker run. Para la gestión de entornos con Docker Compose, mi experiencia me dice que los Docker Compose profiles son una herramienta muy útil.

El tradeoff honesto de externalizar la configuración

La decisión de externalizar la configuración a variables de entorno tiene sus ventajas y desventajas. Es una práctica estándar por una buena razón, pero no es magia.

Lo que ganas:

• Seguridad: Las claves sensibles no están en el repositorio de código.
• Consistencia: El mismo código funciona en cualquier entorno, solo cambia la configuración.
• Facilidad de despliegue: Los deploys son más predecibles, ya que la configuración se gestiona por separado.
• Prevención de errores: Se reducen drásticamente los errores por configuración incorrecta en diferentes entornos.

Lo que complicas:

• Complejidad inicial: Requiere configurar las variables en cada entorno de despliegue.
• Manejo de secretos: Necesitas un sistema para gestionar y rotar estas variables, especialmente las sensibles.
• Curva de aprendizaje: El equipo debe adoptar la disciplina de no hardcodear valores y entender cómo funcionan las variables de entorno.

Una configuración clara y bien gestionada es un elemento indispensable para evitar los problemas que hacen que tu código funcione en local y falle en producción. Si estás diseñando la arquitectura de tu aplicación, te recomiendo considerar también cuándo dividir un proyecto en microservicios para entender cómo la configuración impacta la escalabilidad. Y recuerda que tener un buen README que invite a usar tu proyecto siempre debe incluir cómo configurar las variables de entorno necesarias.