# Portal Maestro de Documentación Técnica ## Sistema de Gestión Dinámica de Subdominios Apache2 (`a2host`) Bienvenido a la suite oficial de documentación técnica de **`a2host`**, el orquestador ligero y panel de control diseñado para la gestión dinámica, segura y automatizada de subdominios sobre servidores web Apache2 en infraestructuras Linux (Ubuntu Server) con severas restricciones de memoria (1 GB de RAM física). Toda la documentación técnica contenida en este directorio ha sido elaborada siguiendo rigurosamente los estándares internacionales de ingeniería de software (**ISO/IEC/IEEE 29148:2018**, **IEEE Std 1016-2009**, **ISO/IEC/IEEE 42010:2011**, **OpenAPI 3.1** y **OWASP ASVS**). --- ## 1. Mapa General de la Suite de Documentación ```mermaid flowchart TD Index["docs/README.md
Portal Maestro"] --> Req["01-requirements/
srs-ieee-29148.md
(Especificación SRS)"] Index --> Arch["02-architecture/
sdd-ieee-1016.md
(Diseño SDD)"] Index --> API["03-api/
api-specification.md
(API REST OpenAPI/RFC 7807)"] Index --> Sec["04-security/
security-model.md
(Seguridad & STRIDE)"] Index --> Dep["05-deployment/
vps-deployment-guide.md
(Despliegue VPS)"] Index --> User["06-user-guides/
admin-manual.md
(Manual Operativo)"] Req -.->|"Trazabilidad Requisitos"| Arch Arch -.->|"Contratos de Interfaz"| API Arch -.->|"Mitigaciones Técnicas"| Sec Arch -.->|"Instalación en Host"| Dep API -.->|"Consumo y Operatoria"| User ``` --- ## 2. Catálogo de Documentos y Especificaciones | Documento | Estándar / Norma | Audiencia Principal | Descripción Sintética | | :--- | :---: | :---: | :--- | | [`01-requirements/srs-ieee-29148.md`](01-requirements/srs-ieee-29148.md) | **ISO/IEC/IEEE 29148:2018** / IEEE Std 830 | Arquitectos, Tech Leads, QA | Especificación formal de requerimientos funcionales (RF-01 a RF-05) y no funcionales (RNF-01 a RNF-04), límites de memoria y matriz de trazabilidad cruzada. | | [`02-architecture/sdd-ieee-1016.md`](02-architecture/sdd-ieee-1016.md) | **IEEE Std 1016-2009** / IEEE 42010 | Desarrolladores, Arquitectos | Diseño detallado de componentes, patrón Strategy (`IApacheDriver` Real vs Mock), máquina de estados del Rollback Atómico, persistencia ligera y diseño Zero-Build. | | [`03-api/api-specification.md`](03-api/api-specification.md) | **OpenAPI 3.1.0** / RFC 7807 | Desarrolladores Frontend/Backend | Especificación formal de contratos HTTP de la API REST (Auth, Users, Subdomains, Folders, Telemetry), esquemas JSON, códigos de estado y ejemplos. | | [`04-security/security-model.md`](04-security/security-model.md) | **OWASP ASVS** / Modelo STRIDE | DevSecOps, Auditores, SysAdmins | Modelo de amenazas, erradicación de inyección shell vía `execFile`, arquitectura SGID `2775`, protección inmutable de `git.conf` y criptografía `scrypt`/HMAC. | | [`05-deployment/vps-deployment-guide.md`](05-deployment/vps-deployment-guide.md) | DevOps / Runbook Operativo | Ingenieros DevOps, SysAdmins | Guía de despliegue paso a paso en el VPS de producción (`elingejose.com`), límites de PM2 (120MB), VirtualHost Apache, Certbot y automatización SSH. | | [`06-user-guides/admin-manual.md`](06-user-guides/admin-manual.md) | Guía de Operaciones y Usuario | Operadores, SysAdmins, Usuarios | Manual práctico de usuario: creación de sitios Modo A y Modo B, explorador de `/var/www`, gestión de roles, resolución de errores sintácticos y rollback. | --- ## 3. Rutas de Lectura Recomendadas según el Rol ### 👨‍💻 Para Desarrolladores de Software (Full-Stack / Backend / Frontend) 1. Iniciar con [`02-architecture/sdd-ieee-1016.md`](02-architecture/sdd-ieee-1016.md) para comprender el flujo de capas, la dualidad de controladores Mock/Real y la interfaz Zero-Build. 2. Consultar [`03-api/api-specification.md`](03-api/api-specification.md) para conocer las firmas de payloads, cabeceras de sesión y respuestas RFC 7807. 3. Revisar [`01-requirements/srs-ieee-29148.md`](01-requirements/srs-ieee-29148.md) para validar criterios de aceptación y pruebas de unidad. ### 🛠️ Para Ingenieros DevOps y Administradores de Sistemas (SysAdmin) 1. Estudiar [`05-deployment/vps-deployment-guide.md`](05-deployment/vps-deployment-guide.md) para configurar PM2, sudoers, Apache2 nativo y Certbot en el VPS. 2. Revisar [`04-security/security-model.md`](04-security/security-model.md) para auditar la configuración de permisos UNIX (`chmod 2775`, `chown ggc:www-data`) y sudoers. 3. Consultar [`06-user-guides/admin-manual.md`](06-user-guides/admin-manual.md) para procedimientos de diagnóstico de emergencias y logs. ### 🛡️ Para Auditores de Seguridad y DevSecOps 1. Examinar [`04-security/security-model.md`](04-security/security-model.md) para verificar la matriz de mitigación de amenazas STRIDE, el uso mandatorio de `execFile` con argumentos vectorizados y el hashing criptográfico. 2. Validar en [`01-requirements/srs-ieee-29148.md`](01-requirements/srs-ieee-29148.md) los requerimientos no funcionales RNF-01 (Memoria) y RNF-02 (Anti-inyección). 3. Inspeccionar [`03-api/api-specification.md`](03-api/api-specification.md) para convalidar las cabeceras de cookies seguras y respuestas sin fugas de información. ### 👤 Para Operadores del Panel y Usuarios Finales 1. Consultar exclusivamente [`06-user-guides/admin-manual.md`](06-user-guides/admin-manual.md) para aprender a crear sitios estáticos (Modo A), proxies inversos (Modo B), pausar servicios y explorar carpetas. --- ## 4. Snapshot de Principios Rectores y Restricciones Críticas Cualquier cambio, ampliación o mantenimiento en el código del sistema debe someterse a las siguientes cuatro restricciones inviolables: 1. **Restricción de Memoria RAM (1 GB VPS):** El proceso Node.js debe mantener un consumo base menor a **35 MB RSS** y un tope absoluto de **120 MB** en PM2. Queda prohibido el uso de Docker o motores de compilación pesados en producción. 2. **Inmunidad contra Inyección en Shell:** Prohibido el uso de `child_process.exec()`. Toda ejecución de comandos del sistema operativo (`a2ensite`, `a2dissite`, `apache2ctl`, `systemctl`) debe realizarse mediante `child_process.execFile` con arrays de argumentos estáticos y validación de nombres mediante `^[a-z0-9-]+$`. 3. **Rollback Atómico Obligatorio:** Antes de recargar Apache (`systemctl reload`), siempre se debe ejecutar `apache2ctl configtest`. Ante cualquier error sintáctico, la transacción debe revertirse de forma atómica sin degradar el servidor web. 4. **Permisos Web SGID 2775:** Todo directorio web en `/var/www/` debe poseer permisos `2775` y propietario `ggc:www-data`, permitiendo despliegues ágiles vía Git/SFTP sin superusuario y lectura garantizada para Apache. --- *Para sugerencias o actualizaciones de esta documentación, abrir un ticket o solicitud de cambio en el repositorio institucional.*