# Despliegue en Namecheap (cPanel, plan Stellar)

Guia paso a paso para publicar el panel en un subdominio. Todo se hace desde
cPanel; la Terminal (SSH) no es necesaria.

> **Que se probo y que no.** El paquete se probo en local tal como correra en el
> servidor: compilado para produccion, ejecutado desde una carpeta aislada, con
> MariaDB 11.4 (la version de Namecheap) y la base creada importando
> `schema.sql`. Lo que no se pudo probar es el panel de cPanel en si: los
> nombres de menus pueden variar un poco segun la version.

---

## 0. Requisitos (revisar una sola vez)

En cPanel deben aparecer estos iconos:

| Seccion  | Icono               |
| -------- | ------------------- |
| Software | Setup Node.js App   |
| Bases    | MySQL Databases     |
| Bases    | phpMyAdmin          |
| Archivos | File Manager        |
| Dominios | Domains / Subdomains |

Si **Setup Node.js App** no aparece, hay que pedirlo a soporte de Namecheap:
sin eso no se puede ejecutar la aplicacion.

---

## 1. Armar el paquete (en tu computador)

```bash
npm run empaquetar
```

Deja en la carpeta `despliegue/`:

| Archivo                    | Para que                                           |
| -------------------------- | -------------------------------------------------- |
| `app.zip`                  | La aplicacion, lista para subir                    |
| `schema.sql`               | Crea las tablas; se importa una sola vez           |
| `variables-de-entorno.txt` | Plantilla de las variables que se cargan en cPanel |

Se compila en tu computador y no en el servidor porque en hosting compartido la
compilacion consume 500-800 MB de memoria y el proceso suele morir a mitad.

---

## 2. Subdominio y HTTPS

1. **cPanel -> Domains** -> crear el subdominio, por ejemplo
   `examenes.tudominio.com`. Deja la carpeta raiz que propone cPanel: la
   aplicacion **no** va ahi.
2. **cPanel -> SSL/TLS Status** -> *Run AutoSSL*. Espera a que el subdominio
   quede con el candado verde (puede tardar unos minutos).
3. **cPanel -> Domains** -> activa **Force HTTPS Redirect** para el subdominio.

> **No te saltes el paso 3.** En produccion la cookie de sesion solo viaja por
> https. Si alguien entra por `http://`, el inicio de sesion "funciona" pero
> vuelve a pedir la contrasena en cada pagina.

---

## 3. Base de datos

**cPanel -> MySQL Databases**

1. *Create New Database*: `examenes`. cPanel le antepone tu usuario y queda
   `CPUSUARIO_examenes`.
2. *Add New User*: usuario `examenes` y una contrasena fuerte (usa el
   generador de cPanel). Queda `CPUSUARIO_examenes`.
3. *Add User To Database*: ese usuario a esa base, con **ALL PRIVILEGES**.

**cPanel -> phpMyAdmin**

4. Selecciona la base `CPUSUARIO_examenes` en la columna izquierda.
5. Pestana **Importar** -> elige `despliegue/schema.sql` -> **Importar**.
6. Deben quedar **10 tablas**.

> `schema.sql` se importa **una sola vez**, en la base vacia. Nunca lo vuelvas a
> importar sobre una base con datos.

---

## 4. Subir la aplicacion

**cPanel -> File Manager**, en tu carpeta personal (`/home/CPUSUARIO`, fuera de
`public_html`):

1. Crea dos carpetas:
   - `examenes-app`: la aplicacion.
   - `examenes-almacenamiento`: fotos de pacientes y firmas.
2. Entra a `examenes-app` -> **Upload** -> sube `app.zip`.
3. Clic derecho sobre `app.zip` -> **Extract** -> luego borra `app.zip`.
4. Comprueba que dentro de `examenes-app` estan `server.js`, `node_modules`,
   `public` y `.next`. Para ver `.next`: *Settings* -> *Show Hidden Files*.

> **Por que dos carpetas.** Cada version nueva reemplaza `examenes-app`
> completa. Si las fotos vivieran adentro, se perderian en la siguiente
> actualizacion.

---

## 5. Crear la aplicacion Node.js

**cPanel -> Setup Node.js App -> Create Application**

| Campo                    | Valor                                   |
| ------------------------ | --------------------------------------- |
| Node.js version          | La mas alta disponible (22.x o 20.x)    |
| Application mode         | Production                              |
| Application root         | `examenes-app`                          |
| Application URL          | el subdominio                           |
| Application startup file | `server.js`                             |

Pulsa **Create**. Luego, en la misma pantalla, **Environment variables -> Add
Variable** con cada una de estas (valores sin comillas):

| Variable             | Valor                                                              |
| -------------------- | ------------------------------------------------------------------ |
| `NODE_ENV`           | `production`                                                       |
| `DATABASE_URL`       | `mysql://CPUSUARIO_examenes:CONTRASENA@localhost:3306/CPUSUARIO_examenes` |
| `AUTH_SECRET`        | un secreto nuevo (ver abajo)                                       |
| `APP_URL`            | `https://examenes.tudominio.com` (sin barra final)                 |
| `ALMACENAMIENTO_DIR` | `/home/CPUSUARIO/examenes-almacenamiento`                          |
| `INSTALACION_TOKEN`  | una clave de al menos 16 caracteres (ver abajo)                    |

Para generar `AUTH_SECRET` e `INSTALACION_TOKEN`, en tu computador:

```bash
node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"
```

Si la contrasena de la base tiene simbolos (`@ : / # ? & %`), codificala antes
de ponerla en `DATABASE_URL`:

```bash
node -e "console.log(encodeURIComponent('LA-CONTRASENA'))"
```

Guarda y pulsa **Restart**.

> **No pulses "Run NPM Install".** El paquete ya trae exactamente las
> dependencias que necesita. Instalar en el servidor bajaria las de desarrollo
> y puede fallar por memoria.

---

## 6. Comprobar que arranco

Abre `https://examenes.tudominio.com/api/salud`. Debe responder:

```json
{"ok":true,"baseDatos":true,"almacenamiento":true}
```

| Si ves                   | Revisa                                                        |
| ------------------------ | ------------------------------------------------------------- |
| `"baseDatos":false`      | `DATABASE_URL`: usuario, contrasena, nombre de la base        |
| `"almacenamiento":false` | `ALMACENAMIENTO_DIR`: que la carpeta exista y la ruta sea exacta |
| Error 503 recien reiniciado | Normal: la app tarda 10-20 s en arrancar. Recarga.         |

---

## 7. Crear el primer administrador

1. Abre `https://examenes.tudominio.com`. Como la base no tiene usuarios, te
   lleva solo a **/instalar**.
2. Escribe el `INSTALACION_TOKEN` y los datos del administrador.
3. Al terminar, `/instalar` deja de existir (responde 404).
4. Recomendado: borra la variable `INSTALACION_TOKEN` en Setup Node.js App y
   pulsa **Restart**.

---

## 8. Dejarlo listo para uso

1. **Usuarios -> Nuevo usuario**: crea al medico con rol *Medico*, sus datos
   profesionales y la imagen de su firma (PNG con fondo transparente).
2. **Configuracion**: revisa los datos del prestador que salen en el certificado.
3. Prueba completa: crea un examen con foto, emitelo, descarga el PDF y
   **escanea el QR con el celular**. Debe abrir
   `https://examenes.tudominio.com/verificar/...`.
4. Anula ese examen de prueba (queda registrado en la auditoria; un certificado
   emitido no se borra).

---

## Actualizar a una version nueva

1. En tu computador: `npm run empaquetar`.
2. **Si la version trae cambios de base de datos**, importa primero en
   phpMyAdmin el archivo nuevo de `prisma/migrations/<fecha>_<nombre>/migration.sql`
   (solo los que aun no se hayan importado). Se entregan junto con la version.
3. **Setup Node.js App -> Stop**.
4. **File Manager -> `examenes-app`**: borra su contenido, sube `app.zip` y
   extraelo. **No toques `examenes-almacenamiento`.**
5. **Setup Node.js App -> Start**.

La aplicacion queda fuera de linea unos minutos. Hazlo fuera del horario de
atencion.

---

## Respaldos

En **cPanel -> Backup** (o *JetBackup*, si aparece), al menos una vez por semana:

- **La base de datos** `CPUSUARIO_examenes`.
- **La carpeta** `examenes-almacenamiento` (fotos y firmas).

Hacen falta las dos: la base sin la carpeta produce certificados sin foto ni
firma, y la carpeta sin la base no sirve de nada. La carpeta `examenes-app` no
hace falta respaldarla: se regenera con `npm run empaquetar`.

---

## Problemas frecuentes

**Inicio de sesion que vuelve a pedir la contrasena.** El sitio se esta abriendo
por `http://`. Activa *Force HTTPS Redirect* (paso 2).

**"Demasiados intentos fallidos".** Tras 5 contrasenas erradas la cuenta queda
bloqueada 15 minutos. Es a proposito: frena que adivinen contrasenas.

**La pagina carga sin estilos.** Falto la carpeta oculta `.next` al extraer.
Activa *Show Hidden Files* y verifica que exista `examenes-app/.next/static`.

**El QR abre otra direccion.** Revisa `APP_URL` y reinicia. El QR se genera al
descargar el PDF, asi que basta con volver a descargarlo; no hay que re-emitir.

**Error sobre "libquery_engine" u "openssl".** El paquete trae los motores de
Prisma para las tres versiones de OpenSSL de CloudLinux. Si aun asi falla,
revisa el registro de errores y comparte el mensaje exacto.

**Donde ver los errores.** En `examenes-app` suele aparecer `stderr.log`. Las
pantallas de error del sistema muestran un *codigo*: buscalo en ese archivo.