Validador de Configuración
Valida archivos de configuración y variables de entorno para prevenir errores en tiempo de ejecución y configuraciones faltantes.
Cuándo Usar
- Trabajar con variables de entorno o archivos de configuración
- Problemas de despliegue o configuración
- El usuario menciona ".env", "config", "variables de entorno" o "ajustes"
Instrucciones
1. Buscar Archivos de Configuración
Buscar:
.env,.env.example,.env.localconfig/,config.js,config.jsonsettings.py,application.ymlappsettings.json,.env.production
2. Detectar Variables Faltantes
Comparar .env.example vs .env:
# Variables en el ejemplo pero no en .env
comm -23 <(grep -o '^[A-Z_]*' .env.example | sort) <(grep -o '^[A-Z_]*' .env | sort)
Variables comunes requeridas:
DATABASE_URL
API_KEY
SECRET_KEY
NODE_ENV
PORT
3. Validar Formato de Variables
Verificar problemas comunes:
// Faltan comillas para valores con espacios
DATABASE_URL=postgres://localhost/db name // Mal
DATABASE_URL="postgres://localhost/db name" // Bien
// Falta protocolo
API_URL=example.com // Mal
API_URL=https://example.com // Bien
// Booleano como cadena
DEBUG=true // Podría interpretarse como cadena
DEBUG=1 // Más explícito
4. Validar Variables Requeridas en Tiempo de Ejecución
Ejemplo en Node.js:
const requiredEnvVars = [
'DATABASE_URL',
'API_KEY',
'JWT_SECRET'
];
const missing = requiredEnvVars.filter(v => !process.env[v]);
if (missing.length > 0) {
throw new Error(`Faltan variables de entorno requeridas: ${missing.join(', ')}`);
}
Ejemplo en Python:
import os
REQUIRED_ENV_VARS = [
'DATABASE_URL',
'SECRET_KEY',
'ALLOWED_HOSTS'
]
missing = [var for var in REQUIRED_ENV_VARS if not os.getenv(var)]
if missing:
raise EnvironmentError(f"Faltan variables de entorno: {', '.join(missing)}")
5. Validación de Tipos
Validar tipos:
const config = {
port: parseInt(process.env.PORT || '3000', 10),
debug: process.env.DEBUG === 'true',
apiUrl: new URL(process.env.API_URL), // Lanza error si es inválido
maxConnections: Number(process.env.MAX_CONNECTIONS),
};
// Validar
if (isNaN(config.port) || config.port < 1 || config.port > 65535) {
throw new Error('PORT debe ser un número de puerto válido');
}
6. Generar .env.example
Crear plantilla desde el .env real:
# Quitar valores, mantener claves
sed 's/=.*/=/' .env > .env.example
O con marcadores de posición:
DATABASE_URL=postgres://usuario:contraseña@localhost:5432/nombrebd
API_KEY=tu_api_key_aqui
SECRET_KEY=generar_secreto_aleatorio
PORT=3000
NODE_ENV=development
7. Esquema de Configuración
Definir esquema (ejemplo con Joi):
const Joi = require('joi');
const envSchema = Joi.object({
NODE_ENV: Joi.string()
.valid('development', 'production', 'test')
.required(),
PORT: Joi.number()
.port()
.default(3000),
DATABASE_URL: Joi.string()
.uri()
.required(),
API_KEY: Joi.string()
.min(32)
.required(),
DEBUG: Joi.boolean()
.default(false),
}).unknown();
const { error, value } = envSchema.validate(process.env);
if (error) {
throw new Error(`Error de validación de configuración: ${error.message}`);
}
module.exports = value;
8. Verificaciones de Seguridad
No hacer commit de secretos:
# Verificar si .env está en .gitignore
if ! grep -q "^\.env$" .gitignore; then
echo "Advertencia: .env no está en .gitignore"
fi
# Buscar secretos hardcodeados en el código
grep -r "api_key.*=.*['\"]" --exclude-dir=node_modules
Problemas comunes de seguridad:
- Contraseñas/claves hardcodeadas
- Secretos por defecto en producción
- Configuraciones sensibles expuestas
- Secretos sin cifrar
9. Configuraciones Específicas por Entorno
Organizar por entorno:
.env.development
.env.staging
.env.production
.env.test
Cargar adecuadamente:
require('dotenv').config({
path: `.env.${process.env.NODE_ENV || 'development'}`
});
10. Documentar Todas las Variables
Crear CONFIG.md:
# Configuración
## Variables de Entorno
### Requeridas
- `DATABASE_URL`: Cadena de conexión PostgreSQL
- Formato: `postgres://usuario:contraseña@host:puerto/bd`
- Ejemplo: `postgres://app:secret@localhost:5432/miapp`
- `API_KEY`: Clave de API de terceros
- Obtener de: https://dashboard.example.com
- Ámbitos requeridos: read, write
### Opcionales
- `PORT`: Puerto del servidor (por defecto: 3000)
- `DEBUG`: Habilitar registro de depuración (por defecto: false)
- `MAX_CONNECTIONS`: Tamaño del pool de base de datos (por defecto: 10)
## Configuración
1. Copiar `.env.example` a `.env`
2. Completar todos los valores requeridos
3. Ejecutar `npm run validate-config` para verificar
11. Script de Validación
Crear scripts/validate-config.js:
const fs = require('fs');
function validateConfig() {
const required = ['DATABASE_URL', 'API_KEY'];
const missing = required.filter(v => !process.env[v]);
if (missing.length > 0) {
console.error(`❌ Faltan: ${missing.join(', ')}`);
process.exit(1);
}
console.log('✓ Todas las variables de configuración requeridas presentes');
}
validateConfig();
12. Mejores Prácticas
- Nunca hacer commit de .env: Siempre agregar a .gitignore
- Mantener .env.example: Mantenerlo actualizado
- Validar al inicio: Fallar rápido si está mal configurado
- Usar valores predeterminados robustos: Fallbacks sensatos
- Documentar todo: Explicar cada variable
- Rotar secretos: Actualizar claves regularmente
- Usar gestores de secretos: Vault, AWS Secrets Manager en producción
- Verificar tipos: Validar tipos, no solo presencia
Archivos de Soporte
templates/config-validator.jstemplates/.env.examplescripts/generate-env-example.sh