# Instalación en cPanel — Sistema de Notas U.E.N. “Alberto Smith”

## Requisito indispensable

El paquete se sube con **Administrador de archivos**, pero no funciona como una página PHP común. El alojamiento debe mostrar una de estas opciones:

- **Setup Python App / Configurar aplicación Python**, o
- **Application Manager / Administrador de aplicaciones** con Phusion Passenger.

Se recomienda Python 3.11 o 3.12, MySQL/MariaDB y un subdominio exclusivo, por ejemplo `notas.sudominio.edu.ve`. La aplicación debe instalarse en la raíz del subdominio, porque sus rutas institucionales usan `/login`, `/secciones`, `/evaluaciones` y `/static`.

## 1. Crear el subdominio

En cPanel → **Dominios**, cree el subdominio que usará el sistema. Active SSL/AutoSSL cuando el DNS ya apunte al alojamiento.

## 2. Crear MySQL

En cPanel → **Asistente de bases de datos MySQL**:

1. Cree una base, por ejemplo `alberto_notas`.
2. Cree un usuario, por ejemplo `notas`.
3. Asigne el usuario a la base con **TODOS LOS PRIVILEGIOS**.
4. Guarde los nombres completos; cPanel normalmente agrega el prefijo de la cuenta, por ejemplo `colegio_alberto_notas`.

## 3. Subir el ZIP

En **Administrador de archivos**, entre en `/home/USUARIO_CPANEL/`, no en `public_html`.

1. Suba el ZIP.
2. Extráigalo.
3. Renombre la carpeta extraída a `notas_alberto_smith`.
4. La ruta final debe ser `/home/USUARIO_CPANEL/notas_alberto_smith/`.

Dentro deben verse `passenger_wsgi.py`, `requirements.txt`, `app/`, `data/` y `tmp/`.

## 4. Configurar las claves

Copie `cpanel.env.example` como `cpanel.env` y edítelo. Complete:

- `SECRET_KEY`: una cadena aleatoria de 64 caracteres.
- `ADMIN_PASSWORD`: contraseña inicial del administrador.
- `MYSQL_DATABASE`, `MYSQL_USER` y `MYSQL_PASSWORD`.
- `SCHOOL_YEAR`.

No agregue comillas alrededor de los valores. Permisos recomendados para `cpanel.env`: **600**.

## 5A. Cuando aparece “Setup Python App”

Cree una aplicación con estos valores:

- Python: **3.11 o 3.12**.
- Application root: `notas_alberto_smith`.
- Application URL: el subdominio, en la ruta raíz `/`.
- Startup file: `passenger_wsgi.py`.
- Entry point: `application`.

Después pulse **Run Pip Install** o instale el archivo `requirements.txt` usando el comando que cPanel muestra para activar el entorno virtual.

## 5B. Cuando aparece “Application Manager”

Registre la aplicación:

- Deployment Domain: el subdominio de notas.
- Base Application URL: `/`.
- Application Path: `notas_alberto_smith`.
- Environment: **Production**.

Instale las dependencias desde la opción de dependencias o desde Terminal:

```bash
cd ~/notas_alberto_smith
pip install -r requirements.txt
```

## 6. Verificar y reiniciar

Con Terminal, dentro del entorno virtual de la aplicación:

```bash
cd ~/notas_alberto_smith
python scripts/diagnostico_cpanel.py
touch tmp/restart.txt
```

Sin Terminal, pulse **Restart** en Setup Python App. En Application Manager vuelva a desplegar o cree/modifique `tmp/restart.txt` desde el Administrador de archivos.

Abra:

```text
https://notas.sudominio.edu.ve/health
```

Debe mostrar `"status":"ok"`. Luego entre en la raíz del subdominio con el usuario de `ADMIN_USERNAME` y la contraseña inicial de `ADMIN_PASSWORD`.

## 7. Permisos

- Carpetas: 755.
- Archivos Python/HTML/CSS/JS: 644.
- `cpanel.env`: 600.
- `data/` y `backups/`: el usuario de cPanel debe poder escribir; normalmente 755 es suficiente.
- Nunca use permisos 777.

## 8. Respaldos

Con Terminal:

```bash
cd ~/notas_alberto_smith
python scripts/backup_cpanel.py
```

Los respaldos se guardan en `backups/`. También active las copias automáticas del proveedor de hosting.

## Errores frecuentes

### “Setup Python App” no aparece

El plan no tiene soporte para aplicaciones Python. El Administrador de archivos por sí solo no puede ejecutar FastAPI. Solicite al proveedor **Python 3.11+, Passenger y Setup Python App/Application Manager**, o use un VPS.

### Error 500

Revise `stderr.log` dentro de la carpeta de la aplicación. Las causas comunes son dependencias no instaladas, datos MySQL incorrectos o `cpanel.env` ausente.

### La página carga, pero no permite iniciar sesión

Compruebe `COOKIE_SECURE=true` y que el sitio abra por HTTPS. Reinicie Passenger después de cambiar `cpanel.env`.

### Cambié ADMIN_PASSWORD y no cambió la clave existente

`ADMIN_PASSWORD` solo crea el administrador durante la primera inicialización. Una vez creada la base, cambie la contraseña desde el sistema. Para reiniciar desde cero tendría que eliminar las tablas o la base, lo que borra los datos.