| .agents | ||
| docs | ||
| public | ||
| src | ||
| test | ||
| .env.example | ||
| .gitignore | ||
| a2host.md | ||
| AGENTS.md | ||
| ecosystem.config.cjs | ||
| ecosystem.config.js | ||
| package-lock.json | ||
| package.json | ||
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
flowchart TD
Index["docs/README.md<br/>Portal Maestro"] --> Req["01-requirements/<br/>srs-ieee-29148.md<br/>(Especificación SRS)"]
Index --> Arch["02-architecture/<br/>sdd-ieee-1016.md<br/>(Diseño SDD)"]
Index --> API["03-api/<br/>api-specification.md<br/>(API REST OpenAPI/RFC 7807)"]
Index --> Sec["04-security/<br/>security-model.md<br/>(Seguridad & STRIDE)"]
Index --> Dep["05-deployment/<br/>vps-deployment-guide.md<br/>(Despliegue VPS)"]
Index --> User["06-user-guides/<br/>admin-manual.md<br/>(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 |
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 |
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 |
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 |
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 |
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 |
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)
- Iniciar con
02-architecture/sdd-ieee-1016.mdpara comprender el flujo de capas, la dualidad de controladores Mock/Real y la interfaz Zero-Build. - Consultar
03-api/api-specification.mdpara conocer las firmas de payloads, cabeceras de sesión y respuestas RFC 7807. - Revisar
01-requirements/srs-ieee-29148.mdpara validar criterios de aceptación y pruebas de unidad.
🛠️ Para Ingenieros DevOps y Administradores de Sistemas (SysAdmin)
- Estudiar
05-deployment/vps-deployment-guide.mdpara configurar PM2, sudoers, Apache2 nativo y Certbot en el VPS. - Revisar
04-security/security-model.mdpara auditar la configuración de permisos UNIX (chmod 2775,chown ggc:www-data) y sudoers. - Consultar
06-user-guides/admin-manual.mdpara procedimientos de diagnóstico de emergencias y logs.
🛡️ Para Auditores de Seguridad y DevSecOps
- Examinar
04-security/security-model.mdpara verificar la matriz de mitigación de amenazas STRIDE, el uso mandatorio deexecFilecon argumentos vectorizados y el hashing criptográfico. - Validar en
01-requirements/srs-ieee-29148.mdlos requerimientos no funcionales RNF-01 (Memoria) y RNF-02 (Anti-inyección). - Inspeccionar
03-api/api-specification.mdpara convalidar las cabeceras de cookies seguras y respuestas sin fugas de información.
👤 Para Operadores del Panel y Usuarios Finales
- Consultar exclusivamente
06-user-guides/admin-manual.mdpara 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:
- 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.
- 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 mediantechild_process.execFilecon arrays de argumentos estáticos y validación de nombres mediante^[a-z0-9-]+$. - Rollback Atómico Obligatorio: Antes de recargar Apache (
systemctl reload), siempre se debe ejecutarapache2ctl configtest. Ante cualquier error sintáctico, la transacción debe revertirse de forma atómica sin degradar el servidor web. - Permisos Web SGID 2775: Todo directorio web en
/var/www/<subdominio>debe poseer permisos2775y propietarioggc: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.