285 lines
8.4 KiB
Markdown
285 lines
8.4 KiB
Markdown
# 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)<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:
|
|
```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
|
|
<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
|
|
```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.
|