8.2 KiB
8.2 KiB
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. 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.comen 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 puerto3005. - 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.comapuntando 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(consudosin contraseña en/etc/sudoers.d/ggc). Apache2 corre bajowww-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 a2ensiteosudo apache2ctldirectamente 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=trueo cuando no exista binarioapache2ctl). - 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,apache2ctlysystemctl reloadsimulados mediante manipulación de symlinks y validación sintáctica básica en memoria/disco.
- Rutas redirigidas a
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.execFileochild_process.spawncon arrays de argumentos (['a2ensite',${subdomain}.conf]). PROHIBIDO concatenar cadenas conchild_process.exec().
2. Modo A — Proyecto Web Estático / PHP (Carpeta)
- Directorio:
/var/www/<subdominio> - Archivo inicial: Generar
/var/www/<subdominio>/index.htmlde 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 bit2775asegura que nuevos ficheros creados porggcvía Git/SFTP hereden el grupowww-datapara que Apache pueda leerlos sin usar sudo).
- VirtualHost canónico (
/etc/apache2/sites-available/<subdominio>.conf):<VirtualHost *:80>ServerName <subdominio>.elingejose.comDocumentRoot /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.comProxyPreserveHost OnAllowEncodedSlashes NoDecodeProxyPass / http://127.0.0.1:<puerto>/ nocanonProxyPassReverse / http://127.0.0.1:<puerto>/(Nota: Usar siempre127.0.0.1, nuncalocalhost, para evitar retrasos de resolución IPv6).
4. Protocolo de Validación y Rollback Atómico
Al crear o modificar cualquier subdominio:
- Escribir
/etc/apache2/sites-available/<subdominio>.conf. - Habilitar sitio:
sudo a2ensite <subdominio>.conf. - Validar sintaxis global:
sudo apache2ctl configtest. - Si
configtestfalla:- Ejecutar rollback inmediato:
sudo a2dissite <subdominio>.confy eliminar el archivo.conf. - Si fue Modo A recién creado, limpiar
/var/www/<subdominio>. - NUNCA ejecutar
reloadsi la sintaxis no es correcta. - Devolver HTTP 422 con el error exacto retornado por Apache.
- Ejecutar rollback inmediato:
- Si
configtestdevuelveSyntax OK:- Ejecutar
sudo systemctl reload apache2. - Devolver HTTP 201 / respuesta exitosa.
- Ejecutar
5. Sitios Protegidos e Inmutabilidad
- Sitios protegidos:
000-default.conf,default-ssl.conf,git.conf(definidos enPROTECTED_SITES). - La API debe rechazar con
403 Forbiddencualquier intento de desactivar, editar o eliminar estos archivos.
6. Eliminación Segura
- Deshabilitar (
sudo a2dissite <subdominio>.conf), borrar.confy 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 esfalse, la carpeta física se preserva intacta.
Configuración y Variables de Entorno (.env)
Variables obligatorias a documentar en .env.example:
# 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)
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:
<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.