a2host/docs/05-deployment/vps-deployment-guide.md

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 a2host recarga el proceso en caliente de forma limpia respetando las conexiones activas.