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

Arquitectura Monolítica (All-in-One Server)

La Arquitectura Monolítica de Mañuti permite desplegar la totalidad del ecosistema empresarial dentro de un único servidor Linux (Ubuntu LTS).

Aunque Mañuti fue concebido para poder desacoplarse en granjas de servidores o clústeres de contenedores, su implementación monolítica es ideal para entornos de desarrollo, Staging, laboratorios de QA o despliegues productivos de mediana escala (soportando hasta 10,000 sesiones activas en apenas 128 MB de RAM en Redis y tiempos de respuesta P95 de 41.98ms).

Topología del Servidor Único

En este esquema, todos los servicios conviven armónicamente en localhost (127.0.0.1) o en la IP privada del nodo, comunicándose a través de sockets Unix y puertos locales sin latencia de red externa:

  • Servidor Web & Proxy Reverso: Nginx (:80 / :443)
  • Runtime de Aplicación: PHP 8.5-FPM (unix:/run/php/php8.5-fpm.sock)
  • Base de Datos Relacional (Core): MariaDB (:3306)
  • Base de Datos Documental (Auditoría): MongoDB 7.0 (:27017)
  • Motor en Memoria (Sesiones, Caché, Colas y Pub/Sub): Redis (:6379)
  • Almacenamiento de Objetos (S3 Compatible): MinIO Server (:9000 API / :9001 Consola)
  • Demonios en Segundo Plano (Supervisor): Laravel Horizon (Workers) + Laravel Reverb (:8080 WebSockets)
  • Motor de Análisis y Grafos: Python 3 + Graphviz

1. Instalación de MongoDB 7.0 (Auditoría NoSQL)

MongoDB almacena de forma asíncrona toda la actividad auditable del sistema sin bloquear las tablas transaccionales de MariaDB.

# 1. Instalar dependencias necesarias
sudo apt-get update
sudo apt-get install gnupg curl software-properties-common -y

# 2. 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. Añadir el repositorio oficial a 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. Instalar e iniciar el servicio mongod
sudo apt-get update
sudo apt-get install -y mongodb-org
sudo systemctl daemon-reload
sudo systemctl start mongod
sudo systemctl enable mongod
sudo systemctl status mongod

2. Instalación de MariaDB (Datos Relacionales Core)

MariaDB aloja las entidades normalizadas del sistema (usuarios, roles, permissions, catalogos, documentos, login, job_batches, failed_jobs).

sudo apt install mariadb-server mariadb-client -y
sudo mysql_secure_installation

Parámetros recomendados durante mysql_secure_installation:

Enter current password for root (enter for none): [Presionar Enter]
Switch to unix_socket authentication [Y/n]: n
Change the root password? [Y/n]: Y
Remove anonymous users? [Y/n]: Y
Disallow root login remotely? [Y/n]: n
Remove test database and access to it? [Y/n]: Y
Reload privilege tables now? [Y/n]: Y

3. Instalación de Redis (Caché, Sesiones y Colas)

sudo apt install redis-server -y
sudo systemctl enable redis-server
sudo systemctl start redis-server

4. Instalación de PHP 8.5 y Extensiones Críticas

Mañuti requiere PHP 8.5 junto con los drivers nativos para Redis, MongoDB, SQLite (para el motor de pruebas automatizadas PHPUnit) y SOAP (para la API Políglota).

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

sudo apt install php8.5-fpm php8.5-cli php8.5-common \
    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 -y

# Habilitar explícitamente el módulo de MongoDB
sudo phpenmod -v 8.5 mongodb

# Reiniciar y verificar PHP-FPM
sudo systemctl restart php8.5-fpm.service
sudo systemctl status php8.5-fpm

5. Instalación y Configuración de Nginx

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

Crear el VirtualHost de Mañuti:

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

Agrega la siguiente configuración (incluyendo el soporte para PHP 8.5 y el túnel Proxy Reverso para los WebSockets de Laravel Reverb):

server {
    listen 80;
    server_name tu_dominio.com www.tu_dominio.com; # O la IP local del servidor (ej. 192.168.1.64)
    root /var/www/framedev12/public;

    add_header X-Frame-Options "SAMEORIGIN";
    add_header X-Content-Type-Options "nosniff";

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

    location / {
        try_files $uri $uri/ /index.php?$query_string;
    }

    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 WebSockets (Laravel Reverb)
    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;
    }

    location ~ /\.ht {
        deny all;
    }
}

Habilitar el sitio:

sudo ln -s /etc/nginx/sites-available/framedev /etc/nginx/sites-enabled/
sudo rm -f /etc/nginx/sites-enabled/default
sudo nginx -t
sudo systemctl restart nginx

6. Instalación de NVM, Node.js y NPM

Requeridos para compilar los activos modulares con Vite y Tailwind CSS.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install node
sudo apt install nodejs npm -y

# Aumentar el límite de File Watchers del kernel Linux para Vite
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf && sudo sysctl -p

7. Instalación de Composer y Clonación del Proyecto

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

# Preparar directorio /var/www y clonar repositorio
sudo chown -R $USER:$USER /var/www
cd /var/www
sudo apt install git -y
git config --global credential.helper store
git clone https://github.com/activemediacdmx/Framedev12.git framedev12

8. Estructura de Permisos y Listas de Control de Acceso (ACLs)

Para que tu usuario de despliegue pueda editar archivos sin sudo y Nginx (www-data) pueda escribir logs y caché sin conflictos de permisos:

# 1. Agregar tu usuario al grupo www-data
sudo usermod -aG www-data $USER

# 2. Asignar propietario y grupo base
sudo chown -R $USER:www-data /var/www/framedev12

# 3. Permisos diferenciados para directorios (775) y archivos (664)
sudo find /var/www/framedev12 -type d -exec chmod 775 {} \;
sudo find /var/www/framedev12 -type f -exec chmod 664 {} \;

# 4. Permisos de escritura en carpetas críticas de Laravel
sudo chmod -R 775 /var/www/framedev12/storage
sudo chmod -R 775 /var/www/framedev12/bootstrap/cache

# 5. Crear y blindar el archivo .env (640)
cd /var/www/framedev12
cp .env.example .env
sudo chmod 640 .env

# 6. Configurar ACLs heredadas para evitar fallos futuros en vistas compiladas
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

9. Instalación de Dependencias del Proyecto

cd /var/www/framedev12
composer update
composer install
npm install
npm run build
php artisan key:generate

10. Instalación de MinIO Server (Almacenamiento S3 Local)

Mañuti utiliza MinIO para almacenar avatares y los mapas vectoriales SVG de arquitectura bajo el protocolo compatible con AWS S3.

10.1. Descarga e Instalación del Binario .deb

sudo apt install wget -y
wget https://dl.min.io/server/minio/release/linux-amd64/minio_20250907161309.0.0_amd64.deb -O minio.deb
sudo dpkg -i minio.deb

10.2. Creación del Volumen de Datos y Usuario de Sistema

sudo mkdir -p /mnt/data
sudo groupadd -g 988 minio-user
sudo useradd -u 999 -g 988 -d /home/minio-user -m -s /bin/sh minio-user
sudo chown -R minio-user:minio-user /mnt/data
sudo chmod 750 /mnt/data

10.3. Configurar /etc/default/minio

sudo nano /etc/default/minio

Contenido del archivo:

MINIO_VOLUMES="/mnt/data"
MINIO_OPTS="--address :9000 --console-address :9001"
MINIO_ROOT_USER=minioadmin
MINIO_ROOT_PASSWORD=PasswordSeguroMinIO123
MINIO_SERVER_URL="http://127.0.0.1:9000"

10.4. Iniciar Servicio y Configurar Cliente mc

sudo systemctl daemon-reload
sudo systemctl start minio
sudo systemctl enable minio

# Instalar cliente de línea de comandos (mc)
wget https://dl.min.io/client/mc/release/linux-amd64/mc
chmod +x mc
sudo mv mc /usr/local/bin/mc

# Conectar alias local, crear bucket y dar acceso de lectura a avatares y mapas
mc alias set local http://localhost:9000 minioadmin PasswordSeguroMinIO123
mc mb local/framedev-bucket
mc anonymous set download local/framedev-bucket/avatars
mc anonymous set download local/framedev-bucket/architecture

11. Configuración del Archivo .env (Monolito)

Edita /var/www/framedev12/.env apuntando los servicios a 127.0.0.1 (o la IP de tu servidor):

APP_NAME="Mañuti Framework"
APP_ENV=production
APP_KEY=base64:TU_LLAVE_GENERADA
APP_DEBUG=false
APP_URL=http://192.168.1.64

# 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=tu_password_sql

# Base de Datos NoSQL (MongoDB Auditoría)
DB_MONGO_CONNECTION=mongodb
DB_MONGO_HOST=127.0.0.1
DB_MONGO_PORT=27017
DB_MONGO_DATABASE=auditoria_db
DB_MONGO_USERNAME=
DB_MONGO_PASSWORD=

# Motor en Memoria (Redis)
CACHE_STORE=redis
SESSION_DRIVER=redis
QUEUE_CONNECTION=redis
QUEUE_FAILED_DRIVER=database-uuids
REDIS_CLIENT=phpredis
REDIS_HOST=127.0.0.1
REDIS_PASSWORD=null
REDIS_PORT=6379

# Servidor WebSocket (Laravel Reverb)
BROADCAST_CONNECTION=reverb
REVERB_APP_ID=manuti-app
REVERB_APP_KEY=manuti-key
REVERB_APP_SECRET=manuti-secret
REVERB_HOST="192.168.1.64"
REVERB_PORT=8080
REVERB_SCHEME=http

VITE_REVERB_APP_KEY="${REVERB_APP_KEY}"
VITE_REVERB_HOST="192.168.1.64"
VITE_REVERB_PORT=8080
VITE_REVERB_SCHEME=http

# Almacenamiento S3 (MinIO)
FILESYSTEM_DISK=s3
AWS_ACCESS_KEY_ID=minioadmin
AWS_SECRET_ACCESS_KEY=PasswordSeguroMinIO123
AWS_DEFAULT_REGION=us-east-1
AWS_BUCKET=framedev-bucket
AWS_ENDPOINT=http://192.168.1.64:9000
AWS_URL=http://192.168.1.64:9000/framedev-bucket
AWS_USE_PATH_STYLE_ENDPOINT=true

12. Instalación del Motor Python 3 + Graphviz (Framedev Architect)

Necesario para la generación asíncrona de mapas de arquitectura SVG desde Horizon:

sudo apt-get install python3 python3-pip python3-venv graphviz -y
sudo apt install python3-graphviz python3-pathspec python3-pyparsing -y

# Configurar el entorno virtual dentro del proyecto
mkdir -p /var/www/framedev12/python/scripts
python3 -m venv /var/www/framedev12/python/venv
/var/www/framedev12/python/venv/bin/pip install --upgrade pip
/var/www/framedev12/python/venv/bin/pip install graphviz pathspec pyparsing boto3 python-dotenv

13. Orquestación de Demonios con Supervisor (Horizon y Reverb)

sudo apt-get install supervisor -y

A. 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

B. Archivo /etc/supervisor/conf.d/reverb.conf

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

Activar ambos demonios:

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

14. Migración, Sembrado Inicial y Cierre de Servicios

Ejecuta las migraciones y los Seeders maestros (Catálogos, Configuración Global, Políticas de Contraseña, Documentos Legales y Rol Super Admin):

cd /var/www/framedev12
php artisan migrate:fresh --seed --force

# Asegurar permisos finales y reiniciar servicios
sudo chown -R $USER:www-data storage bootstrap/cache
sudo chmod -R 775 storage bootstrap/cache
php artisan optimize:clear

sudo systemctl restart php8.5-fpm.service
sudo systemctl restart nginx
sudo supervisorctl restart all
Edita este documento en >> arquitectura-monolitica.md
← Volver a la Landing Page