Mañuti
Mañuti / Docs v1.0
resources/views/pages/frontend/docs/instalacion.md
Última modificación: 27 Oct, 2026

Guía Maestra de Instalación y Despliegue en Servidor Único

Este documento constituye el manual operativo estandarizado para la instalación, aprovisionamiento y puesta en producción de Mañuti (FrameDev v12) en un servidor dedicado con Ubuntu 24.04 LTS.

El procedimiento abarca la pila completa de infraestructura: servidor web Nginx, entorno PHP 8.5 FPM, el esquema de persistencia tri-motor (MariaDB, MongoDB, Redis), almacenamiento de objetos compatible con S3 (MinIO), orquestación de demonios mediante Supervisor (Laravel Horizon y Laravel Reverb) y la arquitectura de permisos POSIX con ACLs.

1. Motor NoSQL Documental (MongoDB 7.0)

MongoDB se utiliza en Mañuti de forma exclusiva para almacenar la Bitácora Forense de Auditoría (auditoria) y el registro de excepciones no estructuradas del sistema (system_errors), garantizando que la escritura masiva de eventos no genere bloqueos de tabla en MariaDB.

1.1 Importación de Llaves y Repositorio Oficial

Ejecute los siguientes comandos para registrar el repositorio oficial de MongoDB 7.0:

# 1. Instalar utilidades de transporte seguro
sudo apt-get install gnupg curl -y

# 2. Descargar e importar la llave GPG oficial de MongoDB
curl -fsSL https://www.mongodb.org/static/pgp/server-7.0.asc | \
   sudo gpg -o /usr/share/keyrings/mongodb-server-7.0.gpg \
   --dearmor

# 3. Registrar el repositorio de la versión 7.0 en la lista de fuentes
echo "deb [ arch=amd64,arm64 signed-by=/usr/share/keyrings/mongodb-server-7.0.gpg ] https://repo.mongodb.org/apt/ubuntu jammy/mongodb-org/7.0 multiverse" | \
   sudo tee /etc/apt/sources.list.d/mongodb-org-7.0.list

# 4. Actualizar índices e instalar el motor
sudo apt-get update
sudo apt-get install -y mongodb-org

1.2 Activación y Puesta en Marcha del Servicio

# Recargar systemd para registrar el nuevo demonio
sudo systemctl daemon-reload

# Iniciar el servicio de base de datos
sudo systemctl start mongod

# Habilitar el arranque automático junto con el sistema operativo
sudo systemctl enable mongod

# Validar que el servicio se encuentre en estado activo (running)
sudo systemctl status mongod --no-pager

1.3 Conector de PHP para MongoDB

Para que Laravel pueda interactuar con la base de datos documental a través del driver mongodb/laravel-mongodb:

# Instalar utilidades de repositorios
sudo apt install software-properties-common -y

# Instalar la extensión compilada para PHP 8.5
sudo apt-get install php8.5-mongodb -y

# Habilitar el módulo en el entorno CLI y FPM
sudo phpenmod -v 8.5 mongodb

2. Motor Relacional Transaccional (MariaDB Server)

MariaDB gestiona los datos relacionales de alta integridad con soporte para transacciones ACID: usuarios, roles, permisos RBAC, catálogos recursivos, seguimiento de lotes (job_batches) y registro de fallos (failed_jobs).

2.1 Instalación del Servidor y Cliente

sudo apt install mariadb-server mariadb-client -y

2.2 Hardening de Seguridad (mysql_secure_installation)

Ejecute el script interactivo de seguridad para blindar el motor relacional:

sudo mysql_secure_installation

Configure las respuestas siguiendo estrictamente esta política:

  • Enter current password for root (enter for none): Presione [Enter] (la instalación inicial no posee clave).
  • Switch to unix_socket authentication [Y/n]: Seleccione n (para permitir autenticación mediante contraseña en conexiones TCP internas).
  • Change the root password? [Y/n]: Seleccione Y e ingrese una contraseña robusta (e.g., RootPassword_Secure_2026!).
  • Remove anonymous users? [Y/n]: Seleccione Y (elimina accesos anónimos inseguros).
  • Disallow root login remotely? [Y/n]: Seleccione n si requiere administración remota vía SSH Tunnel (o Y si solo accederá en localhost).
  • Remove test database and access to it? [Y/n]: Seleccione Y (elimina la base de datos de pruebas).
  • Reload privilege tables now? [Y/n]: Seleccione Y (aplica los cambios inmediatamente en memoria).

3. Motor In-Memory de Alta Velocidad (Redis Server)

Redis opera como el cerebro volátil de Mañuti: gestiona las Sesiones Ultraligeras (520 Bytes por usuario), la memoria caché de catálogos y configuración, el broker de mensajería para Laravel Horizon y el bus Pub/Sub para Laravel Reverb.

# Instalación del servidor Redis
sudo apt install redis-server -y

# Habilitar el inicio automático al bootear el servidor
sudo systemctl enable redis-server

# Iniciar el servicio
sudo systemctl start redis-server

# Verificar conectividad (debe responder PONG)
redis-cli ping

4. Entorno de Ejecución PHP 8.5 (FPM y Extensiones)

Mañuti requiere PHP 8.5 con extensiones específicas para criptografía, compresión, manipulación de imágenes, sockets y protocolos legacy como SOAP.

4.1 Instalación del Repositorio de Ondřej Surý

sudo add-apt-repository ppa:ondrej/php -y
sudo apt-get update

4.2 Instalación del Stack Completo de Extensiones

sudo apt install php8.5-fpm php8.5-mysql php8.5-redis php8.5-mongodb \
    php8.5-sqlite3 php8.5-soap php8.5-mbstring php8.5-xml php8.5-curl \
    php8.5-zip php8.5-bcmath php8.5-intl php8.5-gd php8.5-cli -y

4.3 Verificación del Servicio PHP-FPM

# Reiniciar el socket FastCGI
sudo systemctl restart php8.5-fpm.service

# Confirmar estado operativo
sudo systemctl status php8.5-fpm --no-pager

5. Servidor Web Nginx & Proxy Reverso WSS

Nginx actúa como el punto de entrada primario para el tráfico HTTP convencional y como proxy reverso para la actualización de cabeceras de WebSockets (Upgrade: websocket) hacia Reverb.

5.1 Instalación de Nginx

sudo apt-get update
sudo apt-get upgrade -y
sudo apt install nginx -y

5.2 Configuración del VirtualHost

Cree el archivo de configuración del sitio:

sudo nano /etc/nginx/sites-available/framedev

Pegue la siguiente configuración (ajuste server_name con el dominio o IP de su servidor):

server {
    listen 80;
    server_name tu_dominio.com 192.168.1.122;
    root /var/www/framedev12/public;

    index index.php index.html;
    charset utf-8;

    # Encabezados de Seguridad Básicos
    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

    # Enrutamiento de la Aplicación Laravel
    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    # Procesamiento de PHP mediante FastCGI Socket
    location ~ \.php$ {
        include snippets/fastcgi-php.conf;
        fastcgi_pass unix:/run/php/php8.5-fpm.sock;
        fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
        include fastcgi_params;
    }

    # Proxy Reverso para Laravel Reverb (WebSockets WSS)
    location /app {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        # Evita caídas por inactividad en WebSockets
        proxy_read_timeout 60s;
        proxy_send_timeout 60s;
    }

    # Bloqueo de archivos ocultos (.env, .git)
    location ~ /\. {
        deny all;
    }
}

5.3 Activación del Sitio

# Crear enlace simbólico hacia sites-enabled
sudo ln -s /etc/nginx/sites-available/framedev /etc/nginx/sites-enabled/

# Eliminar la configuración predeterminada de Nginx
sudo rm -f /etc/nginx/sites-enabled/default

# Validar sintaxis de configuración
sudo nginx -t

# Reiniciar el servidor web
sudo systemctl restart nginx

6. Gestor de Versiones Node (NVM), Node.js & NPM

El compilador de activos Vite y Tailwind CSS v4 requieren un entorno Node.js en versión LTS moderna.

# 1. Instalar NVM (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# 2. Cargar variables de entorno de NVM en la sesión actual
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"
source ~/.bashrc

# 3. Instalar la versión LTS de Node.js
nvm install --lts

# 4. Instalar paquetes de sistema para soporte global
sudo apt install nodejs npm -y

# 5. Comprobar versiones instaladas
node -v
npm -v

7. Composer & Clonación del Repositorio

7.1 Instalación Global de Composer

curl -sS https://getcomposer.org/installer | sudo php -- --install-dir=/usr/bin --filename=composer
composer --version

7.2 Preparación del Directorio y Clonación Git

# Asegurar permisos del directorio web para el usuario de despliegue
sudo chown -R $USER:$USER /var/www
cd /var/www

# Instalar Git
sudo apt install git -y

# Opcional en desarrollo: almacenar credenciales de Git localmente
git config --global credential.helper store

# Clonar el proyecto en el directorio framedev12
git clone https://github.com/activemediacdmx/Framedev12.git framedev12

8. Arquitectura de Permisos Linux, Grupos y ACLs

Para que Nginx (www-data) pueda servir la aplicación mientras el desarrollador ($USER) edita archivos por SSH sin requerir sudo, se implementa un modelo de propiedad compartida y listas de control de acceso (ACLs).

8.1 Asignación de Grupos y Permisos Base

# 1. Añadir el usuario del sistema al grupo www-data
sudo usermod -aG www-data $USER

# 2. Asignar dueño ($USER) y grupo (www-data) a la raíz del proyecto
sudo chown -R $USER:www-data /var/www/framedev12

# 3. Permisos en directorios: 775 (rwxrwxr-x)
sudo find /var/www/framedev12 -type d -exec chmod 775 {} \;

# 4. Permisos en archivos: 664 (rw-rw-r--)
sudo find /var/www/framedev12 -type f -exec chmod 664 {} \;

# 5. Permisos de escritura irrestricta para almacenamiento y caché
sudo chmod -R 775 /var/www/framedev12/storage
sudo chmod -R 775 /var/www/framedev12/bootstrap/cache

# 6. Preparación del archivo de entorno (.env)
cd /var/www/framedev12
cp .env.example .env

# 7. Blindaje de seguridad del archivo .env (640: solo lectura para Nginx, nadie más)
sudo chmod 640 .env

8.2 Herencia Automática de Permisos con ACLs (Recomendado)

Las ACLs resuelven el problema de permisos cuando procesos como artisan o git pull generan nuevos archivos con permisos restrictivos:

# Instalar utilidades de ACL
sudo apt install acl -y

# Aplicar permisos recursivos inmediatos
sudo setfacl -R -m u:www-data:rwx storage bootstrap/cache
sudo setfacl -R -m u:$USER:rwx storage bootstrap/cache

# Establecer reglas por defecto para cualquier archivo o carpeta futura
sudo setfacl -R -d -m u:www-data:rwx storage bootstrap/cache
sudo setfacl -R -d -m u:$USER:rwx storage bootstrap/cache

9. Instalación de Dependencias del Proyecto

cd /var/www/framedev12

# 1. Instalar dependencias de PHP optimizadas para producción
composer install --no-dev --optimize-autoloader

# 2. Instalar dependencias de Node.js
npm install

# 3. Compilar los activos con Vite y Tailwind CSS v4
npm run build

# 4. Generar la llave maestra criptográfica de la aplicación (APP_KEY)
php artisan key:generate

10. Almacenamiento de Objetos S3 con MinIO

MinIO proporciona la capa de persistencia para el Object Storage S3, desacoplando los archivos del disco local de los servidores web.

10.1 Descarga e Instalación del Paquete Oficial

sudo apt update
sudo apt install wget -y

# Descargar el paquete oficial .deb para AMD64
wget https://dl.min.io/server/minio/release/linux-amd64/minio_20250907161309.0.0_amd64.deb -O minio.deb

# Instalar el paquete en el sistema
sudo dpkg -i minio.deb

10.2 Configuración del Disco y Usuario del Sistema

# 1. Crear el punto de montaje físico de datos
sudo mkdir -p /mnt/data

# 2. Crear grupo del sistema (GID 988)
sudo groupadd -g 988 minio-user

# 3. Crear usuario de servicio sin login interactivo (UID 999)
sudo useradd -u 999 -g 988 -d /home/minio-user -m -s /bin/sh minio-user

# 4. Asignar propiedad exclusiva a MinIO
sudo chown -R minio-user:minio-user /mnt/data
sudo chmod 750 /mnt/data

10.3 Configuración del Demonio (/etc/default/minio)

Edite el archivo de entorno del servicio:

sudo nano /etc/default/minio

Inyecte los siguientes parámetros:

# Directorio físico donde se almacenarán los objetos
MINIO_VOLUMES="/mnt/data"

# Puertos: 9000 para la API S3 y 9001 para la Consola Web de Administración
MINIO_OPTS="--address :9000 --console-address :9001"

# Credenciales maestras del Root (Modificar por valores seguros)
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=MinioSecretKey_Secure_2026!

# URL de resolución del servidor
MINIO_SERVER_URL="http://192.168.1.125:9000"

10.4 Puesta en Marcha del Servicio MinIO

sudo systemctl daemon-reload
sudo systemctl start minio
sudo systemctl enable minio
sudo systemctl status minio --no-pager

10.5 Creación del Bucket y Configuración del Cliente (mc)

Descargue el cliente oficial de MinIO para la gestión desde terminal:

# Descargar el binario del cliente mc
wget https://dl.min.io/client/mc/release/linux-amd64/mc

# Asignar permisos y mover a la ruta global del sistema
chmod +x mc
sudo mv mc /usr/local/bin/mc

# Crear alias de conexión local
mc alias set local http://localhost:9000 minioadmin MinioSecretKey_Secure_2026!

# Crear el bucket maestro de la plataforma
mc mb local/framedev-bucket

# Establecer política de lectura anónima pública exclusivamente para la carpeta de avatares
mc anonymous set download local/framedev-bucket/avatars

11. Parametrización del Archivo de Entorno (.env)

Edite /var/www/framedev12/.env para sincronizar las conexiones de todos los servicios instalados:

APP_NAME="Mañuti v12"
APP_ENV=production
APP_KEY=base64:XOaVIhC6pv8UGLNo3ABnac7VMmcj4BKdBRQ8yrX7tM8=
APP_DEBUG=false
APP_URL=http://192.168.1.122

# --- BASE DE DATOS RELACIONAL (MariaDB) ---
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=framedev_db
DB_USERNAME=framedev_user
DB_PASSWORD=DatabasePassword_Secure_2026!

# --- PERSISTENCIA EN MEMORIA (Redis) ---
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

CACHE_STORE=redis
SESSION_DRIVER=redis
SESSION_LIFETIME=120
QUEUE_CONNECTION=redis
QUEUE_FAILED_DRIVER=database-uuids

# --- SERVIDOR DE CORREO TRANSACCIONAL (SMTP) ---
MAIL_MAILER=smtp
MAIL_HOST=sandbox.smtp.mailtrap.io
MAIL_PORT=2525
MAIL_USERNAME=usuario_smtp_generico
MAIL_PASSWORD=password_smtp_generica
MAIL_FROM_ADDRESS="[email protected]"
MAIL_FROM_NAME="${APP_NAME}"

# --- AUDITORÍA FORENSE NOSQL (MongoDB 7.0) ---
DB_MONGO_CONNECTION=mongodb
MONGODB_DSN="mongodb://framedev_mongo:[email protected]:27017/framedev_logs?authSource=admin"

# Fallback individual para compatibilidad
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

# --- WEBSOCKETS (Laravel Reverb) ---
BROADCAST_CONNECTION=reverb
REVERB_APP_ID=728491
REVERB_APP_KEY=kr9xqenc91s2vmyyaqv7
REVERB_APP_SECRET=reverb_secret_key_2026!
REVERB_HOST="0.0.0.0"
REVERB_PORT=8080
REVERB_SCHEME=http

# Variables consumidas por Vite en el navegador del cliente
VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="192.168.1.122"
VITE_REVERB_PORT=80
VITE_REVERB_SCHEME="http"

# --- OBJECT STORAGE S3 (MinIO) ---
FILESYSTEM_DISK=s3
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
AWS_USE_PATH_STYLE_ENDPOINT=true

# --- SEGURIDAD & CUMPLIMIENTO PII (ISO 27701) ---
APP_ENCRYPT_PII=false

Al modificar el archivo .env, limpie la caché de configuración:

php artisan config:clear

12. Orquestación de Demonios con Supervisor

Tanto Laravel Horizon (trabajos asíncronos) como Laravel Reverb (servidor WebSocket) deben operar como servicios permanentes con reinicio automático.

12.1 Instalación de Supervisor

sudo apt-get install supervisor -y

12.2 Archivo de Demonio para Horizon (horizon.conf)

Cree el archivo /etc/supervisor/conf.d/horizon.conf:

[program:horizon]
process_name=%(program_name)s
command=/usr/bin/php /var/www/framedev12/artisan horizon
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/framedev12/storage/logs/horizon.log
stopwaitsecs=3600

12.3 Archivo de Demonio para Reverb (reverb.conf)

Cree el archivo /etc/supervisor/conf.d/reverb.conf:

[program:reverb]
process_name=%(program_name)s
command=/usr/bin/php /var/www/framedev12/artisan reverb:start --host=0.0.0.0 --port=8080
autostart=true
autorestart=true
user=www-data
redirect_stderr=true
stdout_logfile=/var/www/framedev12/storage/logs/reverb.log
stopwaitsecs=30

12.4 Carga y Arranque de Demonios

sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start all
sudo supervisorctl status

13. Migraciones y Sembrado Inicial de Base de Datos

Ejecute la creación estructural de tablas relacionales, llaves foráneas y los catálogos base:

cd /var/www/framedev12

# Ejecución limpia de migraciones con sembradores de catálogo, roles y usuario administrador
php artisan migrate:fresh --seed --force

Al concluir el comando se habrán creado:

  1. Tablas de seguridad: roles, permissions, role_user, permission_role.
  2. Tablas de identidad: usuarios, configuracion_usuarios, lost_password.
  3. Tablas de control de sesión: login, login_log.
  4. Tablas de colas persistentes: failed_jobs, job_batches.
  5. Catálogo recursivo maestro: catalogos.
  6. Usuario administrador inicial asignado al rol Super Admin.

14. Hardening y Aseguramiento Final de Permisos

Aplique las reglas de aislamiento para garantizar que no existan brechas de privilegios en el sistema de archivos:

cd /var/www/framedev12

# Asegurar propiedad restringida del .env
sudo chown $USER:www-data .env
sudo chmod 640 .env

# Asegurar bit SGID en la carpeta principal para heredar grupo www-data
sudo chown :www-data .
sudo chmod g+s .

# Permisos de ejecución para binarios de Node
sudo chmod +x node_modules/.bin/*

# Asegurar permisos en carpetas de escritura
sudo chown -R $USER:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache

# Limpieza preventiva de vistas compiladas
php artisan view:clear

15. Puesta en Marcha y Validación de Servicios

Reinicie los servicios del sistema para consolidar el despliegue:

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

# 2. Reiniciar el motor PHP-FPM
sudo systemctl restart php8.5-fpm.service

# 3. Reiniciar el servidor web Nginx
sudo systemctl restart nginx

# 4. Reiniciar los demonios de Supervisor
sudo supervisorctl restart all

Comprobación de Servicios Activos

Verifique que los cinco demonios centrales se encuentren en estado running:

# 1. Nginx
sudo systemctl is-active nginx

# 2. PHP-FPM
sudo systemctl is-active php8.5-fpm

# 3. MariaDB
sudo systemctl is-active mariadb

# 4. Redis
sudo systemctl is-active redis-server

# 5. MongoDB
sudo systemctl is-active mongod

# 6. MinIO
sudo systemctl is-active minio

# 7. Supervisor (Horizon y Reverb)
sudo supervisorctl status

El aplicativo se encuentra completamente instalado, asegurado y listo para ser consumido a través del dominio o dirección IP configurada.

Enlaces Relacionados

Edita este documento en >> instalacion.md
← Volver a la Landing Page