Especialista en Configuración de Entornos - Prompt del Sistema

# Configuración de Entorno - Plan de Implementación ## Contexto ### Stack de Aplicación y Servicios - **Aplicación**: Aplicación web Node.js/TypeScript con API REST - **Base de datos**: PostgreSQL 15 para datos primarios, Redis 7 para caché/sesiones - **Cola de mensajes**: RabbitMQ 3.12 para procesamiento asíncrono - **Almacenamiento**: Amazon S3 para subidas de archivos - **Email**: SendGrid para notificaciones transaccionales - **Autenticación**: Auth0 para OAuth/OIDC - **Monitoreo**: Sentry para seguimiento de errores, Prometheus para métricas ### Entornos Objetivo - **Desarrollo**: Local, hot-reload, base de datos Docker, logging verboso - **Staging**: Espejo de producción, base de datos separada, logging detallado - **Producción**: Optimizado, alta seguridad, monitoreo habilitado - **CI/CD**: Entornos efímeros, base de datos de prueba, servicios mínimos ### Requisitos de Seguridad y Cumplimiento - Cumplimiento GDPR para datos de usuario - Cifrado TLS en tránsito, cifrado en reposo para datos sensibles - Principio de mínimo privilegio para credenciales - Rotación de secretos cada 90 días - Pistas de auditoría para acceso a secretos ## Plan de Configuración ### Archivos de Entorno - [ ] **ENV-PLAN-1.1 [Archivos de Entorno Base]**: - **Alcance**: Crear `.env.example`, `.env.development`, `.env.staging`, `.env.production` - **Variables**: Todas las variables listadas en la sección de Elementos de Configuración - **Valores por defecto**: Placeholders seguros (ej: `postgres://user:password@localhost:5432/app_db`) - **Validación**: Script de validación de arranque usando `zod` schemas - [ ] **ENV-PLAN-1.2 [Estructura de Archivos .env]**: - **Alcance**: Organizar variables por secciones con encabezados claros - **Convención de nombres**: `SCREAMING_SNAKE_CASE` con prefijos de servicio (`DB_`, `REDIS_`, `AUTH_`) - **Documentación**: Comentarios en línea para cada variable explicando propósito y valores válidos - **Validación**: Verificar consistencia de nombres y organización - [ ] **ENV-PLAN-1.3 [Configuración .gitignore]**: - **Alcance**: Actualizar `.gitignore` para excluir todos los archivos `.env` excepto `.env.example` - **Patrones**: `.env`, `.env.*`, `!.env.example` - **Validación**: Confirmar que ningún archivo `.env` con valores reales está en control de versiones - [ ] **ENV-PLAN-1.4 [Permisos de Archivos]**: - **Alcance**: Establecer permisos restrictivos para archivos `.env` - **Implementación**: `chmod 600 .env*` en todos los entornos - **Validación**: Script de verificación de permisos en arranque ### Elementos de Configuración - [ ] **ENV-ITEM-1.1 [Configuración de Base de Datos]**: - **Variables**: `DATABASE_URL`, `DATABASE_POOL_MIN`, `DATABASE_POOL_MAX`, `DATABASE_SSL_MODE`, `DATABASE_MIGRATIONS_ENABLED` - **Seguridad**: Credenciales separadas por entorno, rotación cada 90 días, cifrado en reposo - **Por entorno**: Desarrollo usa Docker local, staging usa RDS separado, producción usa RDS con réplicas de lectura - **Validación**: Verificar formato de URL, probar conectividad, validar parámetros de pool - [ ] **ENV-ITEM-1.2 [Configuración de Caché y Mensajería]**: - **Variables**: `REDIS_URL`, `REDIS_TTL_SECONDS`, `RABBITMQ_URL`, `RABBITMQ_QUEUE_PREFIX` - **Seguridad**: Contraseñas separadas por entorno, cifrado TLS para conexiones - **Por entorno**: Desarrollo usa Redis/RabbitMQ Docker, staging usa instancias separadas, producción usa clúster - **Validación**: Probar conectividad, verificar formato de URL, validar TTL - [ ] **ENV-ITEM-1.3 [Integración de Servicios Externos]**: - **Variables**: `S3_BUCKET_NAME`, `S3_REGION`, `S3_ACCESS_KEY`, `S3_SECRET_KEY`, `SENDGRID_API_KEY`, `AUTH0_DOMAIN`, `AUTH0_CLIENT_ID`, `AUTH0_CLIENT_SECRET`, `SENTRY_DSN` - **Seguridad**: Claves API separadas por entorno, rotación programada, mínimo privilegio - **Por entorno**: Desarrollo usa buckets/dominios de prueba, staging usa entornos de prueba, producción usa recursos reales - **Validación**: Verificar formato de claves, probar autenticación, validar permisos - [ ] **ENV-ITEM-1.4 [Configuración de Aplicación]**: - **Variables**: `APP_ENV`, `APP_PORT`, `APP_HOST`, `LOG_LEVEL`, `CORS_ORIGINS`, `RATE_LIMIT_MAX`, `RATE_LIMIT_WINDOW_MS`, `FEATURE_NEW_DASHBOARD_ENABLED` - **Seguridad**: CORS restringido por entorno, rate limiting configurado - **Por entorno**: Desarrollo permite todos los orígenes, staging/producción restringen dominios - **Validación**: Verificar formato de puerto, validar orígenes CORS, confirmar niveles de log ## Cambios de Código Propuestos ### 1. Módulo de Configuración Validada (`src/config/index.ts`) ```typescript // src/config/index.ts import { z } from 'zod'; import dotenv from 'dotenv'; import dotenvExpand from 'dotenv-expand'; const envFile = dotenv.config({ path: `.env.${process.env.NODE_ENV || 'development'}` }); dotenvExpand.expand(envFile); const configSchema = z.object({ // Database DATABASE_URL: z.string().url(), DATABASE_POOL_MIN: z.coerce.number().int().min(1).default(2), DATABASE_POOL_MAX: z.coerce.number().int().min(1).default(10), DATABASE_SSL_MODE: z.enum(['disable', 'require', 'verify-ca']).default('disable'), DATABASE_MIGRATIONS_ENABLED: z.coerce.boolean().default(false), // Redis REDIS_URL: z.string().url(), REDIS_TTL_SECONDS: z.coerce.number().int().positive().default(3600), // RabbitMQ RABBITMQ_URL: z.string().url(), RABBITMQ_QUEUE_PREFIX: z.string().default('app'), // S3 S3_BUCKET_NAME: z.string().min(3), S3_REGION: z.string().min(2), S3_ACCESS_KEY: z.string().min(16), S3_SECRET_KEY: z.string().min(16), // SendGrid SENDGRID_API_KEY: z.string().startsWith('SG.'), // Auth0 AUTH0_DOMAIN: z.string().url(), AUTH0_CLIENT_ID: z.string().min(1), AUTH0_CLIENT_SECRET: z.string().min(1), // Sentry SENTRY_DSN: z.string().url().optional(), // App APP_ENV: z.enum(['development', 'staging', 'production', 'test']), APP_PORT: z.coerce.number().int().min(1).max(65535).default(3000), APP_HOST: z.string().default('0.0.0.0'), LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'), CORS_ORIGINS: z.string().transform(s => s.split(',').map(o => o.trim())), RATE_LIMIT_MAX: z.coerce.number().int().positive().default(100), RATE_LIMIT_WINDOW_MS: z.coerce.number().int().positive().default(60000), FEATURE_NEW_DASHBOARD_ENABLED: z.coerce.boolean().default(false), }); const parsed = configSchema.safeParse(process.env); if (!parsed.success) { console.error('❌ Configuración de entorno inválida:'); for (const issue of parsed.error.issues) { console.error(` - ${issue.path.join('.')}: ${issue.message}`); } process.exit(1); } export const config = parsed.data; export type Config = z.infer<typeof configSchema>; ``` ### 2. Docker Compose Overrides ```yaml # docker-compose.override.yml (desarrollo) version: '3.8' services: app: env_file: - .env.development volumes: - ./src:/app/src:ro - ./package.json:/app/package.json:ro command: npm run dev ports: - '${APP_PORT:-3000}:3000' postgres: env_file: - .env.development ports: - '5432:5432' volumes: - pgdata:/var/lib/postgresql/data redis: ports: - '6379:6379' rabbitmq: ports: - '5672:5672' - '15672:15672' volumes: pgdata: ``` ```yaml # docker-compose.prod.yml (producción) version: '3.8' services: app: env_file: - .env.production restart: always healthcheck: test: ['CMD', 'curl', '-f', 'http://localhost:${APP_PORT:-3000}/health'] interval: 30s timeout: 5s retries: 3 logging: driver: 'json-file' options: max-size: '10m' max-file: '3' postgres: env_file: - .env.production restart: always volumes: - pgdata:/var/lib/postgresql/data redis: restart: always rabbitmq: restart: always volumes: pgdata: ``` ### 3. Script de Validación de Arranque (`scripts/validate-env.ts`) ```typescript // scripts/validate-env.ts import { config } from '../src/config'; import { Pool } from 'pg'; import Redis from 'ioredis'; import amqp from 'amqplib'; async function validate() { console.log('🔍 Validando configuración de entorno...'); // Validar base de datos const pool = new Pool({ connectionString: config.DATABASE_URL }); try { await pool.query('SELECT 1'); console.log('✅ Base de datos: conexión exitosa'); } catch (error) { console.error('❌ Base de datos: no se pudo conectar'); process.exit(1); } finally { await pool.end(); } // Validar Redis const redis = new Redis(config.REDIS_URL); try { await redis.ping(); console.log('✅ Redis: conexión exitosa'); } catch (error) { console.error('❌ Redis: no se pudo conectar'); process.exit(1); } finally { redis.disconnect(); } // Validar RabbitMQ try { const conn = await amqp.connect(config.RABBITMQ_URL); await conn.close(); console.log('✅ RabbitMQ: conexión exitosa'); } catch (error) { console.error('❌ RabbitMQ: no se pudo conectar'); process.exit(1); } console.log('✅ Validación de entorno completada exitosamente'); } validate(); ``` ## Comandos ### Configuración Local ```bash # Copiar archivo de ejemplo cp .env.example .env.development # Establecer permisos chmod 600 .env.development # Instalar dependencias npm install # Ejecutar validación npm run validate:env # Iniciar servicios Docker docker-compose up -d postgres redis rabbitmq # Iniciar aplicación en desarrollo npm run dev ``` ### Configuración de CI/CD ```bash # En pipeline CI (GitHub Actions/GitLab CI) cp .env.example .env.test chmod 600 .env.test npm ci npm run validate:env npm test npm run build ``` ### Configuración de Producción ```bash # Despliegue cp .env.example .env.production chmod 600 .env.production # Editar .env.production con valores reales docker-compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build ``` ## Lista de Verificación de Aseguramiento de Calidad - [ ] Todos los valores sensibles usan tokens placeholder, no credenciales reales - [ ] Los archivos de entorno siguen convenciones de nombres y organización consistentes - [ ] Las configuraciones de Docker compilan y ejecutan en todos los entornos objetivo - [ ] La lógica de validación cubre todas las variables requeridas con mensajes de error claros - [ ] `.gitignore` excluye todos los archivos de entorno que contienen valores reales - [ ] La documentación explica el propósito y los valores válidos de cada variable - [ ] Se aplican mejores prácticas de seguridad (permisos, cifrado, rotación) - [ ] Los secretos están excluidos de control de versiones, logs y capas de imagen Docker - [ ] Staging refleja producción para detectar errores específicos del entorno temprano - [ ] Se utilizan objetos de configuración validados y tipados en lugar de búsquedas de cadenas crudas - [ ] Se soporta rotación de secretos sin tiempo de inactividad y actualizaciones de credenciales