Despliegue y operación

SIVA soporta cuatro modalidades de ejecución: desarrollo local, Docker Compose en servidor, Podman y versión autónoma en pendrive (Windows/Linux).

Requisitos de infraestructura

• Servidor Linux con Docker Engine + Docker Compose (plugin docker compose o docker-compose standalone). El script de despliegue comprueba ambos.
• Puertos (por defecto): 3000 backend, 80 frontend, 1025/8025 SMTP+UI de Mailpit, 8080/8081 documentación de usuario/sistema.
• Persistencia: volúmenes montados en el host (data/, storage/, public/).
• Correo: SMTP accesible desde el backend. En el despliegue de referencia se usa Mailpit (captura de correo), no un SMTP real.

⚠️ Nota: el compose "de producción" incluye Mailpit. Para producción real hay que sustituir SMTP_HOST/SMTP_PORT por un servidor SMTP corporativo. Ver operacion/despliegue-docker.md.

Diagrama de despliegue

Docker Compose en servidor (deploy/docker/)

Servicio	Imagen / build	Puertos	Volúmenes
backend	../backend (target prod)	3000:3000	./data, ./storage, ./public
frontend	../frontend (target prod, nginx)	80:80	—
mailpit	axllent/mailpit:latest	1025:1025, 8025:8025	—
doc-user	../documentation (SITE=user)	8080:80	—
doc-system	../documentation (SITE=system)	8081:80	—

El frontend (nginx) sirve la SPA y hace reverse proxy de /api/ y /images/ a http://backend:3000, con fallback SPA (try_files ... /index.html) y client_max_body_size 10m.

Pasos de despliegue manual

cd deploy/docker
cp .env.prod.example .env.prod   # ajustar secretos y CORS_ORIGIN
docker compose up -d --build
docker compose ps
curl -fsS http://localhost:3000/api/health

Despliegue automatizado

deploy/docker/desplegar_en_servidor.sh (ejecutar desde local):

1. Prechecks por SSH y de Docker/Compose en el servidor.
2. docker compose down y limpieza del directorio remoto.
3. Generación de metadatos de documentación y rsync -avz --delete con exclusiones.
4. Creación de directorios y copia de assets (data/, storage/, public/).
5. Generación del .env.prod remoto con JWT_SECRET aleatorio a partir de la plantilla local.
6. docker compose up -d --build.
7. Health check contra http://backend:3000/api/health.

Parámetros configurables: SERVER_IP y CORS_ORIGIN.

ℹ️ El script transforma el .env.prod local (ignorado por git). Si no lo tienes, créalo antes a partir de la plantilla: cp .env.prod.example .env.prod.

Podman (deploy/podman/)

• deploy/podman/podman-compose.yml — producción: backend (${BACKEND_PORT:-3000}), frontend (${FRONTEND_PORT:-5173}:80) y mailpit; red siva-network con name explícito.
• deploy/podman/podman-compose.dev.yml — desarrollo: targets dev, montaje de fuentes y API_TARGET: http://backend:3000.
• Scripts: setup.sh (crea data/, storage/, public/), dev.sh, prod.sh.

cd podman
./setup.sh
./dev.sh    # desarrollo
./prod.sh   # producción

Guía completa en operacion/podman.md.

Versión autónoma en pendrive

Genera paquetes autocontenidos con Node portátil:

• deploy/pendrive/linux/preparar.sh → incluye siva.sh que arranca node dist/server.js en el puerto 3000 y abre el navegador con la IP LAN.
• deploy/pendrive/windows/preparar.sh → equivalente siva.bat.

Detalles en entorno/linux-pendrive.md y entorno/windows-pendrive.md.

Variables de entorno en producción

Variable	Obligatoria	Descripción / valor recomendado
PORT	No	3000.
NODE_ENV	No	production (desactiva el logging SQL verboso).
API_PREFIX	No	/api.
DB_PATH	No	./data/siva.db (volumen persistente).
JWT_SECRET	Sí	Cadena larga y aleatoria; cambiar el valor por defecto.
JWT_ACCESS_EXPIRATION	No	1h.
JWT_REFRESH_EXPIRATION	No	7d.
SUPERADMIN_EMAIL / SUPERADMIN_PASSWORD	Sí	Credenciales del superadministrador; rotar en el primer acceso.
LAURA_EMAIL / LAURA_PASSWORD	No	Cuenta de desarrollo; revisar antes de producción.
SUPERVISOR_EMAIL / SUPERVISOR_PASSWORD	No	Cuenta de desarrollo; revisar antes de producción.
SMTP_HOST / SMTP_PORT	No	mailpit/1025 en la demo; SMTP corporativo en real.
SMTP_USER / SMTP_PASS	No	Credenciales SMTP si el servidor las exige.
SMTP_FROM	No	Remitente de los correos.
CORS_ORIGIN	No	Origen del frontend (p. ej. http://192.168.1.80).
RATE_LIMIT_WINDOW_MS	No	900000 (15 min).
RATE_LIMIT_MAX	No	3000 en los compose; por defecto de código 200.
STORAGE_ALLOWED_IMAGE_EXTENSIONS	No	png,jpg,jpeg,gif,webp.
MAX_AVATAR_MB	No	5.

Operación y mantenimiento

• Salud: GET /api/health devuelve { status, timestamp, database }.
• Logs: Winston (backend/src/config/logger.config.ts); en Docker, docker compose logs -f backend.
• Backup: copiar el volumen ./data/siva.db (SQLite) y ./storage/.
• Migraciones: se ejecutan automáticamente al arrancar (migrationsRun:true). Para gestionarlas manualmente, usar los scripts migration:* del backend.
• Jobs: dos cron horarios (expirar-pendientes, expirar-penalizaciones).

CI/CD

⚠️ Nota: no se ha detectado ninguna configuración de CI/CD (.github/workflows, .gitlab-ci.yml, etc.) en el repositorio. El despliegue es manual mediante desplegar_en_servidor.sh.

Documentación relacionada

• operacion/despliegue-docker.md — guía detallada de Docker.
• operacion/podman.md — Podman.
• entorno/windows-pendrive.md / entorno/linux-pendrive.md — versiones autónomas.