# Instalación y operación en VPS

## Qué se instala

Hay dos servicios con responsabilidades diferentes:

| Servicio                              | Responsabilidad                                                                                             |
| ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Node.js ejecutando Next.js**        | Procesar login, páginas dinámicas, acciones del servidor, consultas a la base de datos y archivos privados. |
| **Apache o Nginx como proxy inverso** | Recibir conexiones HTTPS y reenviarlas al proceso Node.js de la aplicación.                                 |

La base MySQL/MariaDB es otro servicio, que puede estar en el mismo VPS o en un servidor accesible desde él. La aplicación también necesita su directorio persistente `.data`.

El navegador se conecta al puerto HTTPS del proxy. Next.js escucha únicamente en `127.0.0.1:3000`. Apache no ejecuta Next.js, y la aplicación no funciona copiándola a `htdocs`. No se configura `output: "export"` ni se genera una carpeta `out`: el sistema necesita ejecución en servidor.

## Requisitos

- Node.js 22 o superior (preferentemente LTS) y Bun 1.3.12.
- Acceso desde el VPS a MySQL/MariaDB y una base de SICCAP preparada para ese entorno.
- Un dominio con HTTPS y un proxy inverso como Apache o Nginx.
- Almacenamiento persistente para `.data` y permisos de escritura para el proceso.
- Acceso a Google Fonts durante la compilación para descargar Poppins.

## Primer despliegue

Clona el repositorio y ejecuta los comandos desde su directorio raíz:

```sh
git clone https://bitbucket.org/icatep-sicap/academia-siccap.git
cd academia-siccap
```

Copia `.env.example` a `.env` antes de instalar: Prisma utiliza las variables de conexión al generar el cliente. Completa las credenciales y después ejecuta:

```sh
bun install --frozen-lockfile
bun run db:validate
bun run db:check
bun run build
```

`db:check` realiza consultas de lectura y no imprime registros. No utilices `db push` ni `migrate reset` para preparar una base existente.

## Variables de entorno

| Variable                     | Uso                                                                |
| ---------------------------- | ------------------------------------------------------------------ |
| `DB_CONNECTION`              | `mysql` o `mariadb`.                                               |
| `DB_HOST`, `DB_PORT`         | Servidor y puerto de la base de datos.                             |
| `DB_DATABASE`                | Base utilizada por la aplicación.                                  |
| `DB_USERNAME`, `DB_PASSWORD` | Credenciales con los permisos necesarios.                          |
| `AUTH_SECRET`                | Secreto de sesiones, privado y estable.                            |
| `AUTH_URL`                   | Dirección pública HTTPS, por ejemplo `https://aula.example.org`.   |
| `AUTH_TRUST_HOST`            | `true` únicamente si el proxy controla los encabezados reenviados. |

Para crear un secreto nuevo puedes ejecutar este comando y guardar el resultado únicamente en `.env`:

```sh
node -e "console.log(require('node:crypto').randomBytes(32).toString('base64'))"
```

## Servicio de aplicación

Ejecuta la compilación con un solo proceso, escuchando en la interfaz local:

```sh
bun run start --hostname 127.0.0.1 --port 3000
```

Configura el gestor de servicios del VPS para iniciar ese comando automáticamente y reiniciarlo si falla. En Linux puede utilizarse systemd. En Windows Server hace falta un gestor que ejecute procesos de Node.js como servicios de Windows; instalar Node.js no registra por sí solo esta aplicación como servicio. Define como directorio de trabajo la raíz del proyecto: las rutas de `.data` se calculan desde allí.

La cuenta del servicio necesita leer `.env` y escribir en `.data` y `.next`. No uses `bun run dev` como servicio de producción. No habilites varios workers mientras foro y notificaciones dependan de archivos locales.

## Apache como proxy inverso

Configura Apache después de confirmar que Next.js responde localmente en `http://127.0.0.1:3000/login`. El proceso de Node.js debe estar activo antes de comprobar el dominio público. El certificado HTTPS y su renovación corresponden al proxy.

Activa `proxy`, `proxy_http`, `headers` y el soporte TLS de la instalación de Apache. Dentro del VirtualHost HTTPS destinado a la aplicación, adapta este bloque:

```apache
ProxyRequests Off
ProxyPreserveHost On
# Descarta direcciones aportadas por el cliente; mod_proxy agrega la direccion real.
RequestHeader unset X-Forwarded-For
RequestHeader set X-Forwarded-Proto "https"
RequestHeader set X-Forwarded-Host "aula.example.org"

# Coincide con el máximo de carga de videos: 512 MiB.
LimitRequestBody 536870912
ProxyTimeout 600

ProxyPass        / http://127.0.0.1:3000/ timeout=600
ProxyPassReverse / http://127.0.0.1:3000/
```

El VirtualHost debe tener un certificado válido y un `ServerName` que coincida con `AUTH_URL`. Comprueba la configuración de Apache antes de recargarla. En un servidor compartido, utiliza un VirtualHost independiente para la aplicación. El proxy debe controlar los encabezados reenviados y conservar el host público.

No publiques `.data`, `.env` ni el directorio completo del proyecto como una carpeta estática de Apache. El acceso a archivos del aula debe pasar por las rutas autorizadas de Next.js.

## Qué sucede si se detiene cada servicio

- Si Node.js se detiene, Apache seguirá activo, pero las solicitudes hacia la aplicación fallarán, normalmente con un error de proxy 502 o 503.
- Si Apache se detiene, el proceso Next.js puede seguir funcionando localmente, pero el dominio público dejará de atender solicitudes.
- Si la base no está disponible, fallarán el acceso y las operaciones que consultan datos.
- Si falta `.data`, los registros de la base no bastan para recuperar documentos, entregas, foros y avisos guardados en disco.

Configura arranque automático y respaldos para los componentes que correspondan al VPS.

## Actualizaciones

1. Haz una copia de la base de datos, `.data` y la configuración del servicio.
2. Conserva `.env` y el directorio persistente `.data` de este entorno.
3. Descarga la versión nueva y ejecuta `bun install --frozen-lockfile`.
4. Compila con `bun run build` y reinicia el servicio.
5. Comprueba el inicio de sesión y el acceso a un aula con usuarios de cada perfil.

El repositorio no contiene las credenciales, la base de datos ni los archivos de las aulas. No sustituyas `.data` al copiar una nueva versión del código.

## Recuperación

Conserva la revisión de Git desplegada junto con cada respaldo. Para volver a una versión anterior, recupera su código, sus dependencias y su compilación; si hubo cambios incompatibles de datos, utiliza también el respaldo correspondiente. Mantén los respaldos en una ubicación distinta al disco de trabajo del VPS.

## Diagnóstico

- **Error de conexión a la base:** revisa variables, conectividad y permisos con `bun run db:check`.
- **Redirección a un host incorrecto:** comprueba `AUTH_URL` y los encabezados del proxy.
- **Sesiones inválidas tras reiniciar:** verifica que `AUTH_SECRET` conserve su valor.
- **Archivos o conversaciones ausentes:** comprueba `.data`, los permisos del servicio y los registros del aula en la base de datos.
- **Cargas rechazadas:** revisa el límite del proxy y los límites de la aplicación: 512 MB para video, 30 MB para documentos del instructor y 15 MB para entregas del alumno.
- **Compilación sin acceso a Poppins:** permite la conexión a Google Fonts durante el build.