# Manual de Despliegue en Servidor VPS ## Sistema de Gestión Dinámica de Subdominios Apache2 (`a2host`) **Entorno de Producción:** Ubuntu Server 22.04 / 24.04 LTS (1 GB RAM) **Host de Destino:** `elingejose.com` (IP: `201.32.134.58`) **Usuario Operativo:** `ggc` (Acceso SSH por llave configurada en alias `vps-jose`) **Versión de a2host:** 1.0.0 **Fecha:** 19 de Noviembre de 2026 **Autor:** DevOps & Redacción Técnica (@docs) --- ### Registro de Revisiones | Versión | Fecha | Autor | Justificación y Cambios | | :---: | :---: | :---: | :--- | | `1.0.0` | 2026-11-19 | DevOps Engineer (@docs) | Creación de la guía integral de despliegue paso a paso en el VPS, orquestación de PM2 con límite de 120MB, configuración de VirtualHost en Apache y pruebas de salud. | --- ## 1. Topología del Servidor y Requisitos Previos El servidor de producción es un nodo VPS con **1 GB de memoria RAM física**. Todas las instrucciones deben ejecutarse asegurando un impacto mínimo en los recursos de la máquina. ```mermaid flowchart TD subgraph Internet["Red Pública"] DNS["DNS Comodín: *.elingejose.com -> 201.32.134.58"] Client["Navegador Administrador / Cliente"] end subgraph VPS["VPS Ubuntu Server (201.32.134.58 | 1 GB RAM)"] Apache["Apache2 (Puertos 80 / 443)
Módulos: proxy, proxy_http, rewrite, headers"] subgraph SitesAvailable["/etc/apache2/sites-available/"] GitConf["git.conf -> 127.0.0.1:3000 (Gitea)"] PanelConf["panel.elingejose.com.conf -> 127.0.0.1:3005"] SubConf[".conf (Dinámicos)"] end subgraph PM2["PM2 Runtime (Usuario ggc)"] AppNode["a2host (Node.js 22 LTS)
Puerto: 3005 | RAM: < 35MB (Max 120MB)"] end subgraph FileSystem["Sistema de Archivos Web"] WebDirs["/var/www/
Permisos: 2775 (ggc:www-data)"] end end Client --> DNS DNS --> Apache Apache -->|Proxy /| GitConf Apache -->|Proxy /| PanelConf PanelConf --> AppNode AppNode -->|Gestión| SitesAvailable AppNode -->|Aprovisionamiento| WebDirs ``` ### 1.1 Checklist de Prerrequisitos en el Host Antes de iniciar, conectarse al VPS mediante el alias SSH ya configurado: ```bash ssh vps-jose ``` Verificar que las dependencias clave se encuentren operativas: ```bash # 1. Comprobar versión de Node.js (Debe ser v22.x LTS) node -v # 2. Comprobar PM2 pm2 -v # 3. Comprobar estado de Apache2 sudo systemctl status apache2 --no-pager # 4. Comprobar módulos necesarios de Apache apache2ctl -M | grep -E 'proxy_module|proxy_http_module|rewrite_module|headers_module' ``` Si faltara algún módulo en Apache, activarlo y recargar: ```bash sudo a2enmod proxy proxy_http rewrite headers sudo systemctl reload apache2 ``` --- ## 2. Preparación del Directorio y Despliegue del Código ### 2.1 Ubicación de la Aplicación El panel se alojará en el directorio personal del usuario `ggc`: `/home/ggc/a2host`. ```bash # Conectado como ggc en el VPS: cd /home/ggc # Clonar o sincronizar el repositorio git clone http://git.elingejose.com/ggc/a2host.git /home/ggc/a2host # o copiar vía rsync desde máquina local: # rsync -avz --exclude 'node_modules' --exclude '.git' ./ vps-jose:/home/ggc/a2host/ cd /home/ggc/a2host ``` ### 2.2 Instalación de Dependencias de Producción Para respetar el límite de 1 GB de RAM, instalar únicamente dependencias de producción omitiendo paquetes de test/dev: ```bash npm ci --omit=dev ``` --- ## 3. Configuración de Variables de Entorno (`.env`) Crear el archivo `.env` en `/home/ggc/a2host/.env` copiando la plantilla base y configurando secretos criptográficos de alta entropía. ```bash # Generar clave secreta para cookies de sesión (64 caracteres hexadecimales) SESSION_KEY=$(openssl rand -hex 32) echo "Generada SESSION_SECRET: $SESSION_KEY" ``` ### 3.1 Contenido Canónico de `/home/ggc/a2host/.env` ```ini # ================================================================= # Configuración de Producción a2host # Servidor: VPS elingejose.com (1 GB RAM) # ================================================================= # Red y Entorno NODE_ENV=production PORT=3005 BASE_DOMAIN=elingejose.com # Rutas del Sistema Operativo WEB_ROOT=/var/www APACHE_SITES_AVAILABLE=/etc/apache2/sites-available APACHE_SITES_ENABLED=/etc/apache2/sites-enabled SYSTEM_USER=ggc # Autenticación y Credenciales Maestras ADMIN_USER=admin ADMIN_PASS=ColocarAquiPasswordExtremadamenteSegura2026! SESSION_SECRET=PEGA_AQUI_LA_CADENA_GENERADA_CON_OPENSSL # Restricciones y Listas Negras Inmutables PROTECTED_SITES=000-default.conf,default-ssl.conf,git.conf,panel.elingejose.com.conf RESERVED_PORTS=22,80,443,3000,3005,3306,5101,5432 # Modo Operativo (false en VPS de Producción) MOCK_APACHE=false ``` Asegurar los permisos del archivo `.env`: ```bash chmod 600 /home/ggc/a2host/.env ``` --- ## 4. Configuración de Procesos PM2 (`ecosystem.config.js`) PM2 gestionará el ciclo de vida del backend Node.js, garantizando reinicio automático ante caídas y limitando el consumo de memoria a **120 MB**. ### 4.1 Archivo `ecosystem.config.js` Verificar que el archivo en la raíz del proyecto contenga: ```javascript module.exports = { apps: [{ name: 'a2host', script: './src/index.js', cwd: '/home/ggc/a2host', instances: 1, exec_mode: 'fork', autorestart: true, watch: false, max_memory_restart: '120M', kill_timeout: 3000, env: { NODE_ENV: 'development' }, env_production: { NODE_ENV: 'production', PORT: 3005, MOCK_APACHE: 'false' } }] }; ``` ### 4.2 Inicio y Registro en el Arranque del Sistema ```bash # Iniciar la aplicación bajo entorno de producción pm2 start /home/ggc/a2host/ecosystem.config.js --env production # Guardar la lista de procesos activos pm2 save # Asegurar que PM2 arranque tras un reboot del VPS (si no se ha configurado previamente) pm2 startup systemd -u ggc --hp /home/ggc ``` --- ## 5. Configuración del VirtualHost en Apache2 (`panel.elingejose.com`) Para acceder al panel de forma segura a través de `http://panel.elingejose.com` (y posteriormente con HTTPS), configuramos un host virtual en Apache que reenvíe el tráfico al puerto local `3005`. ### 5.1 Creación del VirtualHost Crear el archivo `/etc/apache2/sites-available/panel.elingejose.com.conf` con `sudo`: ```apache ServerName panel.elingejose.com ProxyPreserveHost On AllowEncodedSlashes NoDecode # Configuración de Reverse Proxy hacia el proceso Node en 3005 ProxyPass / http://127.0.0.1:3005/ nocanon ProxyPassReverse / http://127.0.0.1:3005/ # Cabeceras de seguridad RequestHeader set X-Forwarded-Proto "http" RequestHeader set X-Real-IP %{REMOTE_ADDR}s # Logs dedicados ErrorLog ${APACHE_LOG_DIR}/panel_error.log CustomLog ${APACHE_LOG_DIR}/panel_access.log combined ``` ### 5.2 Activación y Recarga Segura ```bash # 1. Habilitar el sitio en Apache sudo a2ensite panel.elingejose.com.conf # 2. Validar sintaxis global (Debe retornar 'Syntax OK') sudo apache2ctl configtest # 3. Si la sintaxis es correcta, recargar Apache sudo systemctl reload apache2 ``` ### 5.3 Aprovisionamiento de Certificado SSL/TLS con Let's Encrypt (Opcional/Recomendado) Una vez que el VirtualHost HTTP esté respondiendo: ```bash sudo certbot --apache -d panel.elingejose.com --non-interactive --agree-tos -m dev@elingejose.com --redirect ``` --- ## 6. Verificación Post-Despliegue y Pruebas de Salud Ejecutar las siguientes comprobaciones para validar el correcto funcionamiento: ```bash # 1. Verificación local del endpoint de estadísticas (puerto 3005) curl -s http://127.0.0.1:3005/api/system/stats | jq . # 2. Verificación de proxy a través de Apache curl -I http://panel.elingejose.com # 3. Verificar estado y consumo de memoria del proceso en PM2 pm2 status pm2 desc a2host | grep -E 'memory|status|uptime' # 4. Inspección de los logs en vivo pm2 logs a2host --lines 20 ``` --- ## 7. Procedimiento de Actualización Continua (CI/CD Manual) Para desplegar nuevas versiones del panel sin interrumpir el servicio: ```bash # Desde la máquina local de desarrollo: ssh vps-jose "cd /home/ggc/a2host && git pull origin main && npm ci --omit=dev && pm2 reload a2host" ``` > **Zero-Downtime:** `pm2 reload a2host` recarga el proceso en caliente de forma limpia respetando las conexiones activas.