# NexoCaja: instalación en subdominio

Este paquete contiene únicamente los archivos necesarios para ejecutar NexoCaja. No incluye bases de datos, el módulo ni las credenciales de demostración, pruebas automatizadas ni documentación interna del proyecto.

## Antes de subirlo

El hosting debe ofrecer una aplicación **Node.js**, proceso persistente o una opción similar a **Setup Node.js App**. Subir el ZIP a un hosting que solo ejecute WordPress/PHP no pondrá en marcha NexoCaja.

Requisitos:

- Node.js 22.13.0 o superior; se recomienda Node.js 24 LTS.
- HTTPS activo en el subdominio.
- Puerto entregado por el proveedor al proceso Node.js.
- Carpeta persistente y escribible para SQLite.
- Aplicación instalada en la raíz del subdominio, no en una subcarpeta de otra web.

## Contenido que sí se sube

```text
app.js
package.json
LEEME_PRIMERO.md
MANIFESTO_SHA256.txt
public/
src/
data/LEEME_DATOS.txt
```

`public/` contiene la interfaz y sus imágenes; `src/` contiene el servidor, autenticación, base de datos y cálculos. `data/` se entrega vacío y puede usarse como almacenamiento solo si no se configura una ubicación externa.

## Instalación recomendada en cPanel o panel similar

1. Crea el subdominio y activa su certificado SSL/HTTPS.
2. En **Setup Node.js App**, crea una aplicación con Node.js 22.13 o superior. Selecciona Node.js 24 si está disponible.
3. Usa una carpeta de aplicación propia y asigna como URL la raíz del subdominio.
4. Extrae allí todo el contenido de `NexoCaja-hosting.zip`.
5. Configura `app.js` como archivo de inicio.
6. Añade las variables de entorno indicadas abajo.
7. Inicia o reinicia la aplicación desde el panel.
8. Abre `https://TU-SUBDOMINIO/api/health`. Debe responder `{"ok":true,"service":"NexoCaja"}`.
9. Abre `https://TU-SUBDOMINIO/` y registra la primera cuenta de Administrador con una contraseña fuerte.

No hay dependencias externas. Si el panel exige ejecutar **Run NPM Install**, puede hacerse: no descargará paquetes del proyecto.

## Variables de entorno

| Variable | Valor recomendado | Observación |
| --- | --- | --- |
| `NODE_ENV` | `production` | Activa la cookie de sesión `Secure`; requiere HTTPS. |
| `NEXOCAJA_DEMO` | `0` | Nunca uses `1` en el hosting real. |
| `NEXOCAJA_DATA_DIR` | Ruta absoluta persistente y escribible | Ejemplo: `/home/USUARIO/nexocaja-data`. Es preferible que esté fuera de la carpeta pública del subdominio. |
| `HOST` | Valor indicado por el proveedor | Si el panel no pide uno, omítelo; NexoCaja usa `127.0.0.1`. |
| `PORT` | Puerto entregado por el panel | No lo fijes manualmente salvo instrucción expresa del proveedor. |

La carpeta configurada en `NEXOCAJA_DATA_DIR` debe existir y permitir escritura al proceso Node.js. NexoCaja creará automáticamente `nexocaja.sqlite` al arrancar.

El modo demostración también queda bloqueado por código cuando `NODE_ENV=production`, y su módulo no forma parte del ZIP de hosting.

## Lo que no se debe subir

- `data/` y `data-demo/` del proyecto original, porque pueden contener información o cuentas locales.
- `test/`, `scripts/` y `.codex-spreadsheet-analysis/`.
- `documentacion/`, `AGENTS.md`, `ANTIGRAVITY.md` y `GEMINI.md`.
- `USUARIOS_DE_PRUEBA.txt` y los iniciadores `.bat` o `.command`.
- El archivo XLSX usado como fuente o cualquier hoja con datos reales.
- `node_modules/`, cachés, archivos temporales y el código fuente completo fuera del paquete entregado.
- Archivos `.env`, contraseñas, tokens o copias de seguridad dentro de la carpeta pública.

No copies un `.htaccess` de WordPress dentro del paquete. El panel suele generar las reglas necesarias para enlazar el subdominio con el proceso Node.js.

## Actualizaciones y respaldo

- Antes de actualizar, respalda la carpeta indicada por `NEXOCAJA_DATA_DIR`.
- Para una copia consistente, detén temporalmente la aplicación y copia `nexocaja.sqlite` junto con los archivos `-wal` y `-shm` si existen.
- En una actualización, reemplaza `app.js`, `package.json`, `public/` y `src/`; no sobrescribas la carpeta de datos.
- Conserva al menos una copia anterior del código para poder volver atrás.

## Comprobaciones rápidas

- `https://TU-SUBDOMINIO/api/health` responde correctamente.
- La página principal carga sin advertencias de certificado.
- La primera cuenta creada es el Administrador esperado.
- `NEXOCAJA_DEMO` está desactivado.
- Tras reiniciar la aplicación, la cuenta y los datos siguen disponibles.

Este paquete sirve para una prueba controlada. Antes de manejar información financiera real se necesita una política de respaldo, revisión de seguridad y privacidad, y validación contable de las reglas configuradas.