8.4 KiB
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.
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)<br/>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["<subdominio>.conf (Dinámicos)"]
end
subgraph PM2["PM2 Runtime (Usuario ggc)"]
AppNode["a2host (Node.js 22 LTS)<br/>Puerto: 3005 | RAM: < 35MB (Max 120MB)"]
end
subgraph FileSystem["Sistema de Archivos Web"]
WebDirs["/var/www/<subdominio><br/>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:
ssh vps-jose
Verificar que las dependencias clave se encuentren operativas:
# 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:
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.
# 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:
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.
# 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
# =================================================================
# 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:
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:
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
# 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:
<VirtualHost *:80>
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
</VirtualHost>
5.2 Activación y Recarga Segura
# 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:
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:
# 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:
# 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 a2hostrecarga el proceso en caliente de forma limpia respetando las conexiones activas.