183 lines
8.2 KiB
Markdown
183 lines
8.2 KiB
Markdown
# AGENTS.md — Protocolo Operativo y Arquitectura de a2host
|
|
|
|
Guía para agentes de IA que trabajan en este repositorio. El documento rector de requerimientos del sistema se encuentra en [`a2host.md`](a2host.md). Consultarlo ante cualquier duda sobre el alcance funcional.
|
|
|
|
---
|
|
|
|
## Snapshot del Proyecto & Restricciones de Hardware
|
|
|
|
- **Propósito:** Panel web ligero para gestionar dinámicamente subdominios de `elingejose.com` en Apache2 sobre un VPS Ubuntu.
|
|
- **Límite Crítico de Memoria:** El VPS tiene solo **1 GB de RAM**. El panel corre bajo PM2 con tope estricto de memoria (`max_memory_restart: '120M'`) en el puerto `3005`.
|
|
- **Prohibición de Procesos Pesados:** Prohibido usar Docker, Nginx, frameworks SSR pesados (Next.js/Nuxt) o compiladores en caliente (`ts-node`) en producción. Frontend servido estáticamente (HTML/CSS/JS o Tailwind CDN sin build pesado).
|
|
- **Servidor Web:** Apache2 nativo (`/etc/apache2/sites-available/` y `/etc/apache2/sites-enabled/`). Módulos activos requeridos: `proxy`, `proxy_http`, `rewrite`, `headers`.
|
|
- **DNS:** Ya existe wildcard `*.elingejose.com` apuntando a la IP del VPS (`201.32.134.58`). El backend gestiona únicamente el filesystem local y la configuración de Apache2.
|
|
- **Usuarios del Sistema:** Proceso Node/PM2 corre bajo usuario `ggc` (con `sudo` sin contraseña en `/etc/sudoers.d/ggc`). Apache2 corre bajo `www-data:www-data`.
|
|
|
|
---
|
|
|
|
## Divergencia Crítica: Entorno Local vs VPS
|
|
|
|
- ⚠️ **La máquina de desarrollo local (laptop) NO tiene instalado Apache2.**
|
|
- Si el código invoca `sudo a2ensite` o `sudo apache2ctl` directamente sin abstracción, los tests y la ejecución local fallarán de inmediato.
|
|
- **Arquitectura de Drivers Requerida:** Todo acceso a Apache y sistema de archivos debe encapsularse en un servicio (ej. `ApacheService` / `SystemManager`) que admita modo simulado (`MOCK_APACHE=true` o cuando no exista binario `apache2ctl`).
|
|
- En modo mock:
|
|
- Rutas redirigidas a `./.tmp/apache2/sites-available/` y `./.tmp/apache2/sites-enabled/`.
|
|
- Raíz web redirigida a `./.tmp/www/`.
|
|
- Comandos `a2ensite`, `a2dissite`, `apache2ctl` y `systemctl reload` simulados mediante manipulación de symlinks y validación sintáctica básica en memoria/disco.
|
|
|
|
---
|
|
|
|
## Comandos Clave
|
|
|
|
| Tarea | Comando |
|
|
| --- | --- |
|
|
| Instalar dependencias | `npm install` |
|
|
| Dev server local (modo mock) | `MOCK_APACHE=true npm run dev` (o `npm start`) |
|
|
| Correr suite de tests | `npm test` (pruebas con runner nativo `node --test` o Vitest/Jest ligero) |
|
|
| Test unitario individual | `npm test -- --grep "SubdomainValidation"` (o equivalente del runner) |
|
|
| Lint / Validación estática | `npm run lint` |
|
|
| Arranque en producción (VPS) | `pm2 start ecosystem.config.js --env production` |
|
|
| Guardar estado PM2 | `pm2 save` |
|
|
| Monitorizar recursos en VPS | `pm2 monit` o `pm2 logs a2host` |
|
|
|
|
Flujo habitual de verificación antes de finalizar cambios: `npm test` → `npm run lint` (debe pasar al 100% sin requerir `sudo` ni binarios de Apache en local).
|
|
|
|
---
|
|
|
|
## Reglas de Arquitectura y Modos de Subdominio
|
|
|
|
### 1. Validación Estricta de Entrada (Anti-Inyección)
|
|
- **Regex de subdominio:** Exclusivamente `^[a-z0-9-]+$` (máximo 63 caracteres). Prohibido aceptar caracteres especiales, barras o espacios para evitar command injection y path traversal.
|
|
- **Ejecución de procesos:** Usar siempre `child_process.execFile` o `child_process.spawn` con arrays de argumentos (`['a2ensite', `${subdomain}.conf`]`). **PROHIBIDO** concatenar cadenas con `child_process.exec()`.
|
|
|
|
### 2. Modo A — Proyecto Web Estático / PHP (Carpeta)
|
|
- **Directorio:** `/var/www/<subdominio>`
|
|
- **Archivo inicial:** Generar `/var/www/<subdominio>/index.html` de bienvenida si no existe.
|
|
- **Permisos requeridos (Mandatorio SGID `2`):**
|
|
- `sudo chown -R ggc:www-data /var/www/<subdominio>`
|
|
- `sudo chmod -R 2775 /var/www/<subdominio>`
|
|
*(El bit `2775` asegura que nuevos ficheros creados por `ggc` vía Git/SFTP hereden el grupo `www-data` para que Apache pueda leerlos sin usar sudo).*
|
|
- **VirtualHost canónico (`/etc/apache2/sites-available/<subdominio>.conf`):**
|
|
- `<VirtualHost *:80>`
|
|
- `ServerName <subdominio>.elingejose.com`
|
|
- `DocumentRoot /var/www/<subdominio>`
|
|
- `<Directory /var/www/<subdominio>>`: `Options -Indexes +FollowSymLinks`, `AllowOverride All`, `Require all granted`.
|
|
|
|
### 3. Modo B — Proxy Inverso por Puerto (Node.js, Python, etc.)
|
|
- **Rango de puerto válido:** `1024 - 65535`.
|
|
- **Puertos Reservados (Bloqueo Estricto):** `[22, 80, 443, 3000, 3005, 3306, 5101, 5432]` (incluye Gitea en 3000 y el propio panel en 3005). Tampoco puede reutilizar un puerto ya asignado en otro VirtualHost activo.
|
|
- **VirtualHost canónico (`/etc/apache2/sites-available/<subdominio>.conf`):**
|
|
- `<VirtualHost *:80>`
|
|
- `ServerName <subdominio>.elingejose.com`
|
|
- `ProxyPreserveHost On`
|
|
- `AllowEncodedSlashes NoDecode`
|
|
- `ProxyPass / http://127.0.0.1:<puerto>/ nocanon`
|
|
- `ProxyPassReverse / http://127.0.0.1:<puerto>/`
|
|
*(Nota: Usar siempre `127.0.0.1`, nunca `localhost`, para evitar retrasos de resolución IPv6).*
|
|
|
|
### 4. Protocolo de Validación y Rollback Atómico
|
|
Al crear o modificar cualquier subdominio:
|
|
1. Escribir `/etc/apache2/sites-available/<subdominio>.conf`.
|
|
2. Habilitar sitio: `sudo a2ensite <subdominio>.conf`.
|
|
3. Validar sintaxis global: `sudo apache2ctl configtest`.
|
|
4. **Si `configtest` falla:**
|
|
- Ejecutar rollback inmediato: `sudo a2dissite <subdominio>.conf` y eliminar el archivo `.conf`.
|
|
- Si fue Modo A recién creado, limpiar `/var/www/<subdominio>`.
|
|
- **NUNCA ejecutar `reload` si la sintaxis no es correcta.**
|
|
- Devolver HTTP 422 con el error exacto retornado por Apache.
|
|
5. **Si `configtest` devuelve `Syntax OK`:**
|
|
- Ejecutar `sudo systemctl reload apache2`.
|
|
- Devolver HTTP 201 / respuesta exitosa.
|
|
|
|
### 5. Sitios Protegidos e Inmutabilidad
|
|
- **Sitios protegidos:** `000-default.conf`, `default-ssl.conf`, `git.conf` (definidos en `PROTECTED_SITES`).
|
|
- La API debe rechazar con `403 Forbidden` cualquier intento de desactivar, editar o eliminar estos archivos.
|
|
|
|
### 6. Eliminación Segura
|
|
- Deshabilitar (`sudo a2dissite <subdominio>.conf`), borrar `.conf` y recargar Apache (`sudo systemctl reload apache2`).
|
|
- El borrado físico de `/var/www/<subdominio>` solo se ejecuta si el usuario marca explícitamente un checkbox (`deleteFiles: true`). Si es `false`, la carpeta física se preserva intacta.
|
|
|
|
---
|
|
|
|
## Configuración y Variables de Entorno (`.env`)
|
|
|
|
Variables obligatorias a documentar en `.env.example`:
|
|
|
|
```ini
|
|
# Red y Proceso
|
|
PORT=3005
|
|
NODE_ENV=development
|
|
BASE_DOMAIN=elingejose.com
|
|
|
|
# Rutas del Sistema
|
|
WEB_ROOT=/var/www
|
|
APACHE_SITES_AVAILABLE=/etc/apache2/sites-available
|
|
APACHE_SITES_ENABLED=/etc/apache2/sites-enabled
|
|
SYSTEM_USER=ggc
|
|
|
|
# Autenticación Básica del Panel
|
|
ADMIN_USER=admin
|
|
ADMIN_PASS=cambiar_password_segura
|
|
SESSION_SECRET=minimo_32_caracteres_aleatorios_para_cookies_o_jwt
|
|
|
|
# Restricciones
|
|
PROTECTED_SITES=000-default.conf,default-ssl.conf,git.conf
|
|
RESERVED_PORTS=22,80,443,3000,3005,3306,5101,5432
|
|
|
|
# Modo de Operación
|
|
MOCK_APACHE=false
|
|
```
|
|
|
|
---
|
|
|
|
## Configuración PM2 (`ecosystem.config.js`)
|
|
|
|
```javascript
|
|
module.exports = {
|
|
apps: [{
|
|
name: 'a2host',
|
|
script: './src/index.js',
|
|
instances: 1,
|
|
autorestart: true,
|
|
watch: false,
|
|
max_memory_restart: '120M',
|
|
env_production: {
|
|
NODE_ENV: 'production',
|
|
PORT: 3005,
|
|
MOCK_APACHE: 'false'
|
|
}
|
|
}]
|
|
};
|
|
```
|
|
|
|
---
|
|
|
|
## VirtualHost del Panel (`panel.elingejose.com`)
|
|
|
|
Plantilla de Apache para exponer la aplicación:
|
|
|
|
```apache
|
|
<VirtualHost *:80>
|
|
ServerName panel.elingejose.com
|
|
|
|
ProxyPreserveHost On
|
|
AllowEncodedSlashes NoDecode
|
|
|
|
ProxyPass / http://127.0.0.1:3005/ nocanon
|
|
ProxyPassReverse / http://127.0.0.1:3005/
|
|
|
|
ErrorLog ${APACHE_LOG_DIR}/panel_error.log
|
|
CustomLog ${APACHE_LOG_DIR}/panel_access.log combined
|
|
</VirtualHost>
|
|
```
|
|
|
|
---
|
|
|
|
## Recursos y Skills en el Repositorio
|
|
|
|
- Skills especializadas disponibles en `.agents/skills/`:
|
|
- `scrum-multi-agent-orchestration`: Orquestación y contratos entre agentes.
|
|
- `security-audit` / `web-security-testing`: Auditoría de inyecciones y validaciones.
|
|
- `modern-ui-design-system` / `responsive-mobile-first`: Pautas visuales y accesibilidad.
|
|
- No modificar directamente carpetas bajo `.agents/skills/` salvo instrucción explícita del usuario.
|