# Manual de Usuario y Administración
## Sistema de Gestión Dinámica de Subdominios Apache2 (`a2host`)
**Público Objetivo:** Administradores de Sistemas, Ingenieros DevOps y Operadores Técnicos
**Proyecto:** a2host — Lightweight Subdomain Orchestrator
**Versión de la Aplicación:** 1.0.0
**Fecha:** 19 de Noviembre de 2026
**Autor:** Documentación Técnica & Experiencia de Usuario (@docs)
---
### Registro de Revisiones
| Versión | Fecha | Autor | Justificación y Cambios |
| :---: | :---: | :---: | :--- |
| `1.0.0` | 2026-11-19 | Redactor Técnico (@docs) | Manual operativo integral: Flujos de autenticación, creación Modo A y B, gestión de carpetas, resolución de errores de sintaxis y diagnóstico. |
---
## 1. Introducción y Acceso al Panel
`a2host` es la consola centralizada para aprovisionar y gestionar subdominios bajo `elingejose.com`. Permite administrar hosts virtuales de Apache2 sin necesidad de acceder a la consola SSH para tareas rutinarias, garantizando la estabilidad del servidor mediante validaciones automáticas.
### 1.1 Acceso al Sistema
1. Abra su navegador web e ingrese a la URL del panel:
```text
http://panel.elingejose.com
```
*(o `https://panel.elingejose.com` si SSL está activo)*.
2. Ingrese las credenciales administrativas asignadas en la instalación (configuradas en el archivo `.env`).
3. Presione **Iniciar Sesión**. La sesión se mantendrá activa mediante una cookie criptográfica segura. Si permanece inactivo por más de 8 horas, el sistema solicitará autenticarse nuevamente por seguridad.
```mermaid
flowchart LR
A["Pantalla de Login
/login.html"] -->|"Usuario & Contraseña"| B{"Verificación scrypt"}
B -- "Válido" --> C["Cookie HttpOnly Emitida
Acceso al Dashboard"]
B -- "Fallido (>5 intentos)" --> D["Bloqueo Temporal IP
(15 minutos)"]
```
---
## 2. Descripción General del Dashboard
Al ingresar al panel, se presenta la consola principal dividida en dos zonas estratégicas: **Telemetría de Recursos** y **Gestión de Subdominios**.
```
+-----------------------------------------------------------------------------------------------------+
| a2host | Panel de Control [RAM: 61.6% | RSS: 30MB / 120MB] (Usuario: admin) [Salir] |
+-----------------------------------------------------------------------------------------------------+
| [ + Crear Nuevo Subdominio ] [ Explorador /var/www ] [ Gestión Usuarios ] |
+-----------------------------------------------------------------------------------------------------+
| SUBDOMINIOS ACTIVOS |
|-----------------------------------------------------------------------------------------------------|
| Subdominio | Tipo | Destino | Estado | Acciones |
|-----------------------|----------------|------------------------|---------------|-------------------|
| git.elingejose.com | Proxy Inverso | http://127.0.0.1:3000 | [ PROTEGIDO ] | [ Inmutable ] |
| blog.elingejose.com | Carpeta Web | /var/www/blog | [ HABILITADO] | [Pausar] [Borrar] |
| api.elingejose.com | Proxy Inverso | http://127.0.0.1:5000 | [ PAUSADO ] | [Activar][Borrar] |
+-----------------------------------------------------------------------------------------------------+
```
### 2.1 Tarjetas de Telemetría (Monitoreo de Recursos)
En la cabecera superior se visualizan en tiempo real los indicadores clave del servidor VPS:
- **Memoria RAM del Servidor:** Muestra la memoria física total (1 GB) y el porcentaje utilizado por el sistema operativo, MySQL y Apache.
- **Memoria del Proceso (Node.js):** Informa el consumo de memoria RSS de `a2host` (típicamente entre 25 MB y 35 MB) y el techo de seguridad establecido en PM2 (**120 MB**).
- **Estado de Apache2:** Indicador luminoso en verde (`Activo / Running`) o rojo (`Alerta de Servicio`).
---
## 3. Creación de Subdominios Paso a Paso
Para registrar un nuevo subdominio, haga clic en el botón **`+ Crear Nuevo Subdominio`**. Se desplegará una ventana modal con dos modalidades de configuración:
### 3.1 Modo A — Proyecto Web Estático / PHP (Carpeta Física)
Utilice esta modalidad para sitios HTML, CSS, JavaScript estáticos, aplicaciones web empaquetadas (React/Vue compilados en archivos planos) o sitios PHP.
```mermaid
flowchart TD
FormA["Formulario Modo A:
Nombre: 'portafolio'"] --> SubmitA["Clic en 'Crear Subdominio'"]
SubmitA --> BackendA["Backend a2host"]
BackendA --> Step1["1. Crea carpeta /var/www/portafolio"]
Step1 --> Step2["2. Genera index.html de bienvenida"]
Step2 --> Step3["3. Asigna permisos SGID 2775 (ggc:www-data)"]
Step3 --> Step4["4. Escribe /etc/apache2/sites-available/portafolio.conf"]
Step4 --> Step5["5. Ejecuta 'sudo a2ensite' y 'apache2ctl configtest'"]
Step5 --> Step6["6. Recarga Apache sin interrupción ('systemctl reload')"]
```
#### Instrucciones para el Operador:
1. Seleccione la pestaña **"Carpeta Web (Estático / PHP)"**.
2. **Nombre del Subdominio:** Escriba el prefijo deseado (ejemplo: `portafolio`).
*Nota: Solo se permiten caracteres alfanuméricos en minúsculas y guiones (`a-z`, `0-9`, `-`). El dominio resultante será `portafolio.elingejose.com`.*
3. Haga clic en **"Crear Subdominio"**.
4. **Despliegue de Archivos:** Una vez creado, el directorio `/var/www/portafolio` ya se encuentra configurado con permisos SGID `2775` y propietario `ggc:www-data`.
- Puede conectarse por SFTP o SSH con el usuario `ggc` y subir sus archivos directamente a `/var/www/portafolio`.
- Puede inicializar un repositorio Git dentro de la carpeta sin utilizar `sudo`. Apache podrá leer automáticamente los nuevos ficheros creados.
---
### 3.2 Modo B — Proxy Inverso por Puerto (Node.js, Python, Go, Docker)
Utilice esta modalidad para redirigir peticiones públicas hacia servicios web, APIs o microservicios que ya se encuentren escuchando en un puerto TCP interno de la máquina.
```mermaid
flowchart TD
FormB["Formulario Modo B:
Nombre: 'bot-api'
Puerto: 8080"] --> SubmitB["Clic en 'Crear Proxy'"]
SubmitB --> BackendB["Backend a2host"]
BackendB --> CheckPort{"¿Puerto Válido y Libre?
(1024-65535, No Reservado)"}
CheckPort -- "No (ej. 3000 o 22)" --> ErrorPort["Error: Puerto Reservado por el Sistema"]
CheckPort -- "Sí" --> StepB1["1. Escribe sites-available/bot-api.conf
con ProxyPass a 127.0.0.1:8080"]
StepB1 --> StepB2["2. Ejecuta 'sudo a2ensite' y 'apache2ctl configtest'"]
StepB2 --> StepB3["3. Recarga Apache ('systemctl reload')"]
```
#### Instrucciones para el Operador:
1. Seleccione la pestaña **"Proxy Inverso por Puerto"**.
2. **Nombre del Subdominio:** Escriba el nombre deseado (ejemplo: `bot-api`).
3. **Puerto de Destino:** Ingrese el puerto TCP donde corre su servicio interno (ejemplo: `8080`).
- El puerto debe encontrarse en el rango de **1024 a 65535**.
- **Puertos Bloqueados por Seguridad:** El sistema impedirá asignar puertos reservados del sistema como `22` (SSH), `80` (HTTP), `443` (HTTPS), `3000` (Gitea), `3005` (Panel de Control), `3306` (MySQL) o `5432` (PostgreSQL).
4. Haga clic en **"Crear Proxy"**.
5. Las peticiones hacia `http://bot-api.elingejose.com` se redirigirán instantáneamente de forma transparente hacia `http://127.0.0.1:8080`.
---
## 4. Gestión de Subdominios Existentes
Para cada subdominio listado en la tabla, el operador dispone de acciones rápidas:
### 4.1 Pausar / Desactivar un Subdominio (`Toggle`)
- Si requiere suspender temporalmente un sitio web sin borrar sus archivos ni su configuración, presione el botón **`Pausar`** (icono de pausa o alternador).
- **Acción del sistema:** Ejecuta `sudo a2dissite .conf` y recarga Apache.
- El archivo `.conf` y la carpeta `/var/www/` se mantienen intactos.
- Cuando desee reactivarlo, haga clic en **`Activar`**.
### 4.2 Eliminación Segura de un Subdominio
Para eliminar permanentemente un VirtualHost:
1. Haga clic en el botón de eliminación (icono de papelera) en la fila del subdominio.
2. Se abrirá un diálogo de confirmación con una casilla crítica:
- **`[ ] Conservar archivos en /var/www/` (Predeterminado):** Deshabilita el VirtualHost y elimina el archivo `.conf` en Apache, pero los archivos de su aplicación se conservan intactos en el disco.
- **`[x] Eliminar también la carpeta y todos los archivos en disco`:** Si marca esta casilla, el sistema purgará irreversiblemente el directorio web.
3. Confirme la acción presionando **"Eliminar Definitivamente"**.
> **Protección Inmutable:** Los sitios críticos como `git.elingejose.com` (`git.conf`) y la configuración base de Apache (`000-default.conf`) están bloqueados por hardware/software. No mostrarán botones de acción ni podrán ser alterados mediante el panel.
---
## 5. Explorador de Carpetas Web (`/var/www/`)
El módulo **Explorador de Carpetas** permite auditar el estado del almacenamiento web:
1. Haga clic en **"Explorador /var/www"** en el menú superior.
2. Se listarán todas las carpetas aprovisionadas en el sistema de archivos con:
- Nombre de la carpeta.
- Permisos UNIX actuales (debe reflejar `2775`).
- Propietario y grupo (`ggc:www-data`).
- Peso total en disco y número de archivos.
3. Al hacer clic sobre una carpeta, puede inspeccionar la lista de archivos contenidos, sus tamaños individuales y sus fechas de modificación.
---
## 6. Gestión de Usuarios y Operadores
Los usuarios con rol `admin` disponen del módulo de administración de accesos:
1. Haga clic en **"Gestión Usuarios"**.
2. **Crear Nuevo Operador:** Ingrese nombre de usuario, nombre completo, contraseña y seleccione el rol:
- **Administrador (`admin`):** Control total del panel y usuarios.
- **Operador (`operator`):** Puede crear y gestionar subdominios, pero no puede purgar directorios críticos ni crear otros usuarios.
3. **Cambiar Contraseña:** Seleccione un usuario de la lista e introduzca la nueva clave. Se regenerará automáticamente el hash `scrypt`.
---
## 7. Diagnóstico y Resolución de Problemas (Troubleshooting)
### 7.1 Comprensión del "Rollback Atómico"
Si al crear un subdominio o modificar una directiva la pantalla muestra un mensaje de error en color rojo con un código `422 Unprocessable Entity`:
```text
[ALERTA DE SINTAXIS APACHE]
AH00526: Syntax error on line 4 of /etc/apache2/sites-available/nuevo-sitio.conf:
Invalid command 'ProxyPassInvalid', perhaps misspelled or defined by a module not included.
-> Transacción abortada. Rollback ejecutado: El sitio fue deshabilitado y removido. Apache sigue funcionando con normalidad.
```
**¿Qué ocurrió?**
El sistema ejecutó una prueba preventiva con `apache2ctl configtest`. Como Apache detectó un error en la configuración, el mecanismo de protección de `a2host` canceló la operación, eliminó el archivo defectuoso y **no recargó Apache**. Gracias a esto, los demás sitios en producción (como Gitea y el propio panel) continuaron operando sin interrupción.
### 7.2 Casos Comunes de Error y Soluciones
| Síntoma / Mensaje | Causa Raíz | Solución Recomendada |
| :--- | :--- | :--- |
| `Puerto 3000 reservado` | Intento de crear un proxy apuntando al puerto de Gitea u otro servicio interno protegido. | Seleccione un puerto disponible entre 1024 y 65535 no asignado a servicios del sistema. |
| `El subdominio ya existe` | Ya existe un archivo `.conf` con el mismo nombre en `sites-available`. | Utilice un nombre diferente o elimine previamente el subdominio antiguo si ya no está en uso. |
| `Error 403: Sitio Protegido` | Intento de deshabilitar o eliminar `git.conf` o `000-default.conf`. | Esta operación está prohibida por diseño para evitar la caída de la infraestructura base. |
| Al ingresar al subdominio público responde error `502 Bad Gateway` | En Modo B (Proxy), el servicio interno (Node/Python) no está corriendo en el puerto indicado. | Conéctese por SSH y verifique que su aplicación esté activa en el puerto: `pm2 status` o `netstat -tlpn`. |
| En Modo A responde `403 Forbidden` al entrar en la web | La carpeta carece de un archivo `index.html` o `index.php` y las directivas prohíben listar directorios. | Suba un archivo `index.html` a la carpeta `/var/www//`. |
### 7.3 Comandos Útiles de Diagnóstico en el Servidor (Vía SSH)
En caso de requerir soporte directo en la consola del VPS:
```bash
# Conectarse al servidor mediante el alias configurado
ssh vps-jose
# Ver logs del panel a2host en tiempo real
pm2 logs a2host
# Comprobar sintaxis manual de Apache
sudo apache2ctl configtest
# Ver los últimos errores globales del servidor Apache
sudo tail -n 30 /var/log/apache2/error.log
```