# Despliegue en cPanel (Node.js + MySQL)

Guía completa para desplegar Empadronamiento VFB en hosting cPanel con soporte Node.js y base de datos MySQL/MariaDB.

---

## Requisitos del hosting

- cPanel con soporte **Node.js** (Phusion Passenger o CloudLinux)
- **Node.js 18.x** o superior disponible
- **MySQL 5.7+** o **MariaDB 10.6+**
- Acceso a **SSH** (recomendado) o **File Manager** de cPanel
- Al menos **512 MB RAM** disponibles para la app

---

## Paso 1 — Preparar la base de datos

### Opción A: Asistente cPanel (sin SSH)

1. En cPanel → **Bases de datos MySQL**
2. Crear base de datos: `usuario_empadronamiento`
3. Crear usuario MySQL: `usuario_vfbuser` con contraseña segura
4. Asignar usuario a la base de datos con **Todos los privilegios**

> cPanel prefija automáticamente el nombre del usuario de cPanel al nombre de la BD y del usuario MySQL. El nombre real será algo como `micuenta_empadronamiento`.

### Opción B: phpMyAdmin o CLI

```sql
CREATE DATABASE empadronamiento_vfb
  CHARACTER SET utf8mb4
  COLLATE utf8mb4_unicode_ci;

CREATE USER 'vfb_user'@'localhost' IDENTIFIED BY 'TuPasswordSeguro123!';
GRANT ALL PRIVILEGES ON empadronamiento_vfb.* TO 'vfb_user'@'localhost';
FLUSH PRIVILEGES;
```

---

## Paso 2 — Subir el código

### Opción A: Git (recomendado)

```bash
# Conectar por SSH al servidor
ssh usuario@tuservidor.com

# Ir al directorio web (ajustar según hosting)
cd ~/public_html   # o ~/domains/tudominio.com/public_html

# Clonar el repositorio
git clone https://github.com/imaginativocom/empadronamiento-mysql.git empadronamiento
cd empadronamiento
```

### Opción B: File Manager / FTP

1. Comprimir el proyecto localmente (sin `node_modules/` ni `.next-build/`)
2. Subir el archivo `.zip` via File Manager de cPanel
3. Extraer en el directorio deseado

---

## Paso 3 — Crear el archivo `.env`

Crea el archivo `.env` en la raíz del proyecto:

```bash
cp .env.example .env
nano .env   # o editar via File Manager
```

Ejemplo de configuración para producción:

```env
DATABASE_URL="mysql://micuenta_vfbuser:TuPasswordSeguro123!@localhost:3306/micuenta_empadronamiento"
NEXTAUTH_URL="https://tudominio.com"
NEXTAUTH_SECRET="genera-esto-con-openssl-rand-base64-32"
UPLOAD_DIR="/home/micuenta/empadronamiento-uploads"
MAX_UPLOAD_MB="10"
NODE_ENV="production"
SEED_ADMIN_EMAIL="admin@tudominio.com"
SEED_ADMIN_PASSWORD="AdminPassword123!"
```

> Crear el directorio de uploads FUERA del directorio web para evitar acceso público:
> ```bash
> mkdir -p ~/empadronamiento-uploads
> chmod 755 ~/empadronamiento-uploads
> ```

---

## Paso 4 — Instalar dependencias

```bash
# Instalar dependencias de producción
npm install --omit=dev

# El script postinstall ejecuta prisma generate automáticamente
```

> Si el servidor tiene restricciones de memoria, puede ser necesario instalar con:
> ```bash
> node --max-old-space-size=512 $(which npm) install --omit=dev
> ```

---

## Paso 5 — Ejecutar migraciones y seed

```bash
# Aplicar migraciones (crea todas las tablas)
npm run prisma:migrate:deploy

# Poblar datos iniciales (roles + admin)
npm run prisma:seed
```

---

## Paso 6 — Compilar la aplicación

```bash
npm run build
```

La build se genera en `.next-build/` (configurado en `next.config.ts`).

> Si el build falla por memoria insuficiente:
> ```bash
> NODE_OPTIONS="--max-old-space-size=512" npm run build
> ```

---

## Paso 7 — Configurar la aplicación Node.js en cPanel

### En el panel cPanel → "Configurar aplicación Node.js"

| Campo | Valor |
|-------|-------|
| Versión de Node.js | 18.x o superior |
| Modo de aplicación | Production |
| Raíz de la aplicación | `/home/micuenta/public_html/empadronamiento` |
| URL de la aplicación | `/` (o subdominio) |
| Archivo de inicio | `server.js` |

### Variables de entorno en cPanel

Agrega todas las variables del `.env` directamente en la sección "Variables de entorno" del panel de la aplicación Node.js. Esto es preferible a subir el `.env` al servidor.

---

## Paso 8 — Iniciar la aplicación

En el panel cPanel → "Aplicaciones Node.js" → clic en **"Ejecutar JS Script"** o **"Reiniciar"**.

O via SSH:

```bash
# Iniciar en background
node server.js &

# O con el comando de cPanel (Passenger se encarga de gestionar el proceso)
```

---

## Mantenimiento

### Actualizar la aplicación

```bash
cd ~/public_html/empadronamiento

# Descargar cambios
git pull origin main

# Instalar dependencias nuevas (si las hay)
npm install --omit=dev

# Ejecutar migraciones pendientes
npm run prisma:migrate:deploy

# Recompilar
npm run build

# Reiniciar (desde panel cPanel o SSH)
```

### Backup de la base de datos

```bash
# Exportar base de datos completa
mysqldump -u vfb_user -p empadronamiento_vfb > backup_$(date +%Y%m%d).sql

# Restaurar
mysql -u vfb_user -p empadronamiento_vfb < backup_20260531.sql
```

También puedes usar **phpMyAdmin** en cPanel para importar/exportar.

### Backup de archivos subidos

```bash
# Comprimir directorio de uploads
tar -czf uploads_backup_$(date +%Y%m%d).tar.gz ~/empadronamiento-uploads/
```

---

## Solución de problemas comunes

### Error: "Can't connect to MySQL server"

- Verificar que el host sea `localhost` (en cPanel MySQL siempre es localhost)
- Verificar usuario y contraseña en `DATABASE_URL`
- Verificar que el usuario tenga permisos sobre la base de datos

### Error: "Module not found" en build

```bash
# Regenerar cliente Prisma
npm run prisma:generate
npm run build
```

### Error: "EACCES permission denied" en uploads

```bash
chmod 755 ~/empadronamiento-uploads
```

### La app no arranca (Passenger)

1. Revisar el archivo `tmp/restart.txt` (toca el archivo para forzar reinicio):
   ```bash
   touch ~/public_html/empadronamiento/tmp/restart.txt
   ```
2. Revisar logs en cPanel → "Registros de errores"

### Memoria insuficiente en build

```bash
# Ajustar en next.config.ts → experimental.cpus: 1 (ya configurado)
# O forzar con variable de entorno:
NODE_OPTIONS="--max-old-space-size=512" npm run build
```

---

## Notas de seguridad

- Nunca subir el archivo `.env` al repositorio Git (está en `.gitignore`)
- Usar **HTTPS** en producción (`NEXTAUTH_URL` con `https://`)
- Cambiar las credenciales del seed admin antes del primer despliegue
- El directorio `uploads` debe estar FUERA del directorio web público
- Rotar `NEXTAUTH_SECRET` si se sospecha que fue comprometido