Guía Integral de Configuración de Entorno e Infraestructura

Este manual técnico reúne la especificación completa para la parametrización, dimensionamiento y configuración de bajo nivel de Mañuti (FrameDev v12). Su propósito es servir como documento de referencia para administradores de sistemas (SysAdmins), ingenieros DevOps y arquitectos de software encargados del aprovisionamiento en entornos de desarrollo, pruebas y producción.

1. Requisitos de Hardware y Dimensionamiento (Sizing)

El consumo de recursos de Mañuti varía según el rol operativo del servidor (despliegue en Monolito Único o segregación en Bare Metal Distribuido).

1.1 Matriz de Especificaciones Mínimas y Recomendadas

1.2 Métricas de Consumo Comprobadas en Producción

• Sesiones de Usuario en Redis: 520 Bytes por sesión activa. 10,000 usuarios concurrentes consumen únicamente ~5.2 MB de memoria RAM.
• Latencia P95 de Respuesta HTTP: 41.98 ms medidos bajo pruebas de estrés concurrentes con k6 a 50 Virtual Users (VUs) continuos.
• Huella de Memoria de PHP 8.5-FPM: ~32 MB a 48 MB por worker activo sirviendo peticiones web.

2. Requisitos de Red y Segmentación Perimetral

2.1 Especificaciones de Conectividad

• Ancho de Banda Externo: Mínimo simétrico de 100 Mbps (Recomendado: 1 Gbps para streaming de WebSockets y carga de archivos a MinIO).
• Red Interna (LAN / VLAN Privada): Interconexión Gigabit Ethernet (1 GbE) o 10 GbE.
• Latencia Máxima Inter-Nodo: Inferior a 2 ms entre la capa web y los nodos de persistencia (MariaDB, Redis, MongoDB).
• MTU (Maximum Transmission Unit): 1500 estándar (o 9000 Jumbo Frames si los switches de la red privada lo soportan para optimizar I/O hacia MinIO y MariaDB).

2.2 Matriz Rápida de Puertos (Políticas de Tráfico)

Consulte la Matriz de Comunicaciones & UFW para la configuración granular.

[CLIENTES INTERNET] 
       | (Puertos 80, 443 TCP)
       v
[LOAD BALANCER]
       |---> [Web Nodes]   : Puerto 80 TCP (Solo tráfico desde IP de LB)
       |---> [Reverb]      : Puerto 8080 TCP (WebSocket WSS Upgrade)
       |---> [MinIO CDN]   : Puertos 80 / 443 TCP (Descarga directa pública)
       |
[RED INTERNA LAN]
       |---> [MariaDB]     : Puerto 3306 TCP (Exclusivo para Web y Workers)
       |---> [Redis]       : Puerto 6379 TCP (Web, Workers, Reverb Pub/Sub)
       |---> [MongoDB]     : Puerto 27017 TCP (Web y Workers)
       |---> [MinIO API]   : Puerto 9000 TCP (Subidas internas S3 PutObject)
       |---> [MinIO Web]   : Puerto 9001 TCP (Consola administrativa restringida)

3. Anatomía Exhaustiva del Archivo de Entorno (.env)

A continuación se detalla la totalidad de variables requeridas por Mañuti, agrupadas por dominio operativo con sus valores recomendados para producción.

3.1 Identidad del Sistema y Entorno Core

# Nombre de la aplicación (usado en correos, layouts y exportaciones)
APP_NAME="Mañuti v12"

# Entorno de ejecución: 'production' en servidores reales, 'local' en desarrollo
APP_ENV=production

# Llave criptográfica maestra de 32 bytes (Generada con: php artisan key:generate)
# ¡NUNCA REGENERAR EN PRODUCCIÓN! Si cambia, se destruye la capacidad de descifrar PII.
APP_KEY=base64:XOaVIhC6pv8UGLNo3ABnac7VMmcj4BKdBRQ8yrX7tM8=

# Modo de depuración: Obligatoriamente FALSE en producción para evitar fugas de traza
APP_DEBUG=false

# Zona horaria base del servidor (Los usuarios adaptan su hora mediante UserTimezoneMiddleware)
APP_TIMEZONE=UTC

# URL absoluta pública de acceso a la plataforma (sin barra final)
APP_URL=https://plataforma.empresa.com

# Idioma base y fallback
APP_LOCALE=es
APP_FALLBACK_LOCALE=es

3.2 Persistencia Relacional Principal (MariaDB)

DB_CONNECTION=mysql
DB_HOST=127.0.0.1          # IP del nodo SQL (ej: 192.168.1.123 en clúster)
DB_PORT=3306
DB_DATABASE=framedev_db
DB_USERNAME=framedev_user
DB_PASSWORD=DatabasePassword_Secure_2026!

3.3 Auditoría Forense NoSQL (MongoDB 7.0)

# Conexión primaria documental
DB_MONGO_CONNECTION=mongodb

# DSN unificado de MongoDB con base de autenticación administrativa
MONGODB_DSN="mongodb://framedev_mongo:[email protected]:27017/framedev_logs?authSource=admin"

# Variables de compatibilidad individual
DB_MONGO_HOST=127.0.0.1
DB_MONGO_PORT=27017
DB_MONGO_DATABASE=framedev_logs
DB_MONGO_USERNAME=framedev_mongo
DB_MONGO_PASSWORD=MongoPassword_Secure_2026!
DB_MONGO_AUTH_DATABASE=admin

3.4 Drivers de Memoria, Sesión y Colas (Redis 7.0)

# Desacoplamiento total a memoria RAM
CACHE_STORE=redis
SESSION_DRIVER=redis
SESSION_LIFETIME=120       # Minutos de expiración de sesión inactiva
QUEUE_CONNECTION=redis
QUEUE_FAILED_DRIVER=database-uuids # Persistencia relacional de excepciones

# Conexión al servidor Redis
REDIS_CLIENT=phpredis      # Extensión nativa de C de PHP 8.5
REDIS_HOST=127.0.0.1       # IP del nodo Redis (ej: 192.168.1.124 en clúster)
REDIS_PASSWORD=null        # Contraseña de Redis (si se configuró requirepass)
REDIS_PORT=6379

3.5 Servidor WebSockets en Tiempo Real (Laravel Reverb)

BROADCAST_CONNECTION=reverb

# Credenciales maestras de la aplicación de WebSockets
REVERB_APP_ID=728491
REVERB_APP_KEY=kr9xqenc91s2vmyyaqv7
REVERB_APP_SECRET=reverb_secret_key_2026!

# Configuración del demonio en el servidor (escucha en 0.0.0.0 o IP local)
REVERB_HOST="0.0.0.0"
REVERB_PORT=8080
REVERB_SCHEME=http

# Escalado horizontal Pub/Sub
REVERB_SCALING_ENABLED=true
REVERB_SCALING_CHANNEL=reverb-scaling

# Variables leídas por el cliente web (Vite) en el navegador del operador
VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="plataforma.empresa.com" # Dominio/IP pública con certificado SSL
VITE_REVERB_PORT=443
VITE_REVERB_SCHEME="https"

3.6 Object Storage S3 Distribuido (MinIO)

# Disco de archivos por defecto
FILESYSTEM_DISK=s3

# Credenciales de acceso al Bucket
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=MinioSecretKey_Secure_2026!
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=framedev-bucket
AWS_ENDPOINT=http://192.168.1.125:9000
AWS_URL=http://192.168.1.125:9000/framedev-bucket

# Obligatorio para MinIO y emuladores compatibles con S3
AWS_USE_PATH_STYLE_ENDPOINT=true

3.7 Servidor de Correo Transaccional (SMTP)

MAIL_MAILER=smtp
MAIL_HOST=smtp.proveedor.com
MAIL_PORT=587
MAIL_USERNAME=usuario_autenticacion
MAIL_PASSWORD=password_o_api_key
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

3.8 Cumplimiento Normativo y Privacidad PII (ISO 27701)

# Control de cifrado simétrico AES-256 en base de datos para PII (Perfil EAV)
# true: Guarda hashes cifrados en MariaDB | false: Guarda texto plano legible
APP_ENCRYPT_PII=false

# Clave secreta compartida para validar firmas criptográficas de Webhooks entrantes
WEBHOOK_CLIENT_SECRET=WebhookSecret_Key_HMAC_SHA256_2026!

4. Configuración Especializada de Servicios

4.1 Afinación de Redis (/etc/redis/redis.conf)

Para soportar concurrencia y evitar caídas por agotamiento de RAM (Out Of Memory):

# Permitir conexiones desde nodos web en red privada (o 127.0.0.1 en monolito)
bind 0.0.0.0 ::1

# Política de expulsión de claves ante saturación de memoria
# volatile-lru: Desecha claves con expiración previa; nunca toca sesiones persistentes
maxmemory 512mb
maxmemory-policy volatile-lru

# Persistencia RDB y AOF (Garantiza que un reinicio de Redis no destruya sesiones vivas)
save 900 1
save 300 10
appendonly yes
appendfsync everysec

Reiniciar el motor: sudo systemctl restart redis-server

4.2 Afinación de MinIO S3 (/etc/default/minio)

MINIO_VOLUMES="/mnt/data"
MINIO_OPTS="--address :9000 --console-address :9001"
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=MinioSecretKey_Secure_2026!
MINIO_SERVER_URL="http://192.168.1.125:9000"

Reiniciar el motor: sudo systemctl restart minio

4.3 Afinación de MariaDB (/etc/mysql/mariadb.conf.d/50-server.cnf)

[mysqld]
# Aceptar conexiones de la red privada
bind-address = 0.0.0.0

# Soporte completo para emojis y caracteres multilingües
character-set-server = utf8mb4
collation-server     = utf8mb4_unicode_ci

# Límite de conexiones simultáneas
max_connections = 300

# Tamaño de pool de búfer de InnoDB (asignar 50-70% de la RAM dedicada a SQL)
innodb_buffer_pool_size = 4G
innodb_log_file_size    = 512M

Reiniciar el motor: sudo systemctl restart mariadb

4.4 Afinación de MongoDB (/etc/mongod.conf)

net:
  port: 27017
  bindIp: 0.0.0.0

security:
  authorization: enabled

Reiniciar el motor: sudo systemctl restart mongod

5. Política de Permisos del Sistema de Archivos (POSIX & ACLs)

Para asegurar que los procesos de ejecución web (www-data), los procesos worker de background (supervisor), la línea de comandos de Artisan y los despliegues SSH convivan sin conflictos de permisos:

# 1. Vincular el usuario del sistema con el grupo de Nginx
sudo usermod -aG www-data $USER

# 2. Asignar propiedad compartida
sudo chown -R $USER:www-data /var/www/framedev12

# 3. Permisos octales base
sudo find /var/www/framedev12 -type d -exec chmod 775 {} \;
sudo find /var/www/framedev12 -type f -exec chmod 664 {} \;

# 4. Asignar bit SetGID (SGID) en carpetas clave
# Obliga a que todo archivo nuevo herede automáticamente el grupo www-data
sudo chmod g+s /var/www/framedev12
sudo chmod g+s /var/www/framedev12/storage
sudo chmod g+s /var/www/framedev12/bootstrap/cache

# 5. Blindaje del archivo de variables (.env)
# 640: El usuario dueño lee/escribe, el servidor web solo lee, el mundo no tiene acceso
sudo chmod 640 /var/www/framedev12/.env
sudo chown $USER:www-data /var/www/framedev12/.env

# 6. Reglas de herencia POSIX ACL (Evita el fallo 'Permission denied' en logs futuros)
sudo apt install acl -y
sudo setfacl -R -m u:www-data:rwx storage bootstrap/cache
sudo setfacl -R -m u:$USER:rwx storage bootstrap/cache
sudo setfacl -R -d -m u:www-data:rwx storage bootstrap/cache
sudo setfacl -R -d -m u:$USER:rwx storage bootstrap/cache

6. Ciclo de Vida y Protocolo de Aplicación de Cambios

Siempre que se actualice una variable en .env o un parámetro en configuracion_sistema:

# 1. Purgar la caché de configuración en disco
php artisan config:clear

# 2. Purgar caché de rutas y vistas
php artisan route:clear
php artisan view:clear

# 3. En entornos de producción: Regenerar caché monolítica para máximo rendimiento
php artisan config:cache
php artisan route:cache
php artisan view:cache

# 4. REINICIAR DEMONIOS DE SUPERVISOR (Obligatorio para que Horizon y Reverb lean el nuevo .env)
sudo supervisorctl restart all

Enlaces Relacionados

• Instalación y Requisitos
• Visión General de la Arquitectura
• Matriz de Comunicaciones & UFW
• Redis Total: Sesiones, Caché & Locks
• Object Storage S3 Distribuido (MinIO)