77 lines
6.8 KiB
Markdown
77 lines
6.8 KiB
Markdown
# 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<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`](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/<subdominio>` 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.*
|