1. Antes de empezar

1.1 Requisitos del servidor

El instalador verifica estos requisitos automáticamente al iniciarse. Asegurate de que el servidor cumple con todos antes de comenzar.

Componente	Mínimo	Recomendado	Notas
Sistema Operativo	Linux (cualquier distro)	Ubuntu 22.04 LTS	No compatible con Windows ni macOS
RAM	8 GB	16 GB o más	Ver tabla de modelos LLM en §2.5
CPU	4 núcleos	8 núcleos	Más núcleos = menor latencia en modo CPU
Disco	40 GB libres	80 GB libres	Los modelos LLM ocupan 5–15 GB c/u
Docker	24.0+	Última versión	`docker --version`
Docker Compose	v2.0+	Última versión	`docker compose version`
Python	3.10	3.11 o 3.12	Para ejecutar el installer
Ollama	0.3+	Última versión	Opcional si se usa API externa (Groq/OpenAI)
Moodle	4.4	4.5 o 5.0	Ya instalado y funcionando
GPU (opcional)	—	VRAM ≥ 8 GB	Sin GPU funciona, con mayor latencia

Importante El servidor debe tener salida a internet para descargar imágenes Docker y el modelo LLM. Los puertos 8052 (engine) y 5435 (base de datos) deben estar disponibles.

1.2 Preparar Moodle

Antes de ejecutar el instalador, realizá los siguientes pasos en el panel de administración de Moodle:

Habilitar Web Services: Ir a Administración del sitio → Características avanzadas y activar Habilitar servicios web.
Habilitar el protocolo REST: Ir a Administración del sitio → Plugins → Servicios web → Gestionar protocolos y activar REST.
Crear un token de servicio web para SAIPA:
- Ir a Administración del sitio → Plugins → Servicios web → Gestionar tokens
- Crear un token para el usuario administrador y el servicio SAIPA Web Service
- Copiar el token generado — lo pedirá el wizard en el Paso 3

Nota Si el servicio SAIPA Web Service no aparece en la lista, instalar primero el plugin local_saipa manualmente desde Moodle antes de ejecutar el wizard. El installer también puede instalarlo automáticamente si seleccionás el método de configuración B o C.

1.3 Obtener el instalador

Descargá el instalador desde schaller-ponce.com.ar/descargas ingresando tu código de acceso. Una vez descargado el ZIP:

unzip saipa-installer.zip
cd saipa-installer
pip install -r requirements.txt

Si el servidor no tiene Ollama instalado y vas a usar un modelo LLM local, instalalo antes de continuar:

curl -fsSL https://ollama.com/install.sh | sh

2. Paso a paso del wizard

Iniciá el wizard con:

python3 installer.py install

El wizard es interactivo. Podés presionar Enter para aceptar los valores por defecto (mostrados entre corchetes).

2.1 Detección de entorno

Detección automática de hardware y requisitos

El wizard detecta y muestra una tabla con el estado del entorno:

RAM, CPU, núcleos, presencia de GPU y VRAM disponible
Versiones de Docker y Docker Compose
Estado de Ollama (si está instalado)
Disponibilidad de los puertos necesarios

No hay nada que ingresar en este paso. Si algún requisito falla, el wizard lo señala con ❌ y sugiere la acción correctiva antes de continuar.

Si Docker falla Verificar que el usuario que ejecuta el installer tenga permisos Docker: sudo usermod -aG docker $USER y reiniciar sesión.

2.2 Selección de componentes

¿Qué plugins instalar?

¿Instalar SAIPA? REQUERIDO

Asistente docente con IA + detección de riesgo de abandono. Seleccionar Y.

¿Instalar EVAL-IA? OPCIONAL

Generación automática de evaluaciones con IA. Puede instalarse junto con SAIPA o de forma independiente.

Ambos plugins comparten el mismo motor de IA (saipa-engine). Instalarlos juntos no requiere recursos adicionales.

2.3 Conexión a Moodle

Datos de conexión a Moodle

URL de Moodle

Ejemplo: https://moodle.universidad.edu.ar — debe incluir https:// si el sitio tiene SSL.

Token del Web Service SAIPA

El token de 32 caracteres generado en el paso §1.2. El wizard valida que el token sea correcto antes de continuar.

Hostname público de Moodle

Solo el dominio, sin https://. Ejemplo: moodle.universidad.edu.ar. Se usa para generar la URL del panel docente en el resumen final.

Detección automática El wizard detecta la versión de Moodle (4.x o 5.0+) y descarga automáticamente el ZIP de plugin compatible.

2.4 Validación de licencia

License key

SAIPA License Key

Formato: SP-XXXX-XXXXXXXX-XXXXXXXX. Entregada por Schaller & Ponce con la contratación del servicio.

El wizard valida la licencia contra el servidor de Schaller & Ponce en tiempo real. Una licencia válida muestra el nombre del cliente y el plan contratado.

Si falla la validación Verificar que el servidor tenga salida a internet y que la licencia no esté expirada. Para problemas con la licencia, contactar a soporte@schaller-ponce.com.ar.

2.5 Selección del modelo LLM

Modelo de lenguaje (LLM)

El wizard recomienda automáticamente el mejor modelo según el hardware detectado. La tabla siguiente muestra los tiers disponibles:

Tier	Condición	Modelo	Latencia aprox.
GPU-L	GPU con VRAM ≥ 16 GB	qwen2.5:14b	2–4 seg/resp
GPU-M	GPU con VRAM ≥ 8 GB	qwen2.5:7b	3–6 seg/resp
CPU-L	RAM ≥ 32 GB, sin GPU	qwen2.5:7b-q4_K_M	15–30 seg/resp
CPU-M	RAM ≥ 16 GB, sin GPU	gemma3:4b	20–40 seg/resp
API	Cualquier hardware	Groq / OpenAI (externo)	1–3 seg/resp

Modo CPU Si el servidor no tiene GPU, el sistema funciona correctamente pero con mayor latencia. Recomendamos informar a los usuarios docentes sobre los tiempos de respuesta esperados.

Podés aceptar el tier recomendado o ingresar cualquier nombre de modelo Ollama disponible.

2.6 Configuración de Telegram

Bot de Telegram (opcional)

Token del bot de Telegram OPCIONAL

Obtenido desde @BotFather en Telegram. Formato: 1234567890:ABCdef... — Dejar vacío para omitir.

Username del bot OPCIONAL

Ejemplo: saipa_asistente_bot (sin @). Solo requerido si se ingresó token.

Con Telegram configurado, los alumnos reciben notificaciones de riesgo y pueden interactuar con el asistente directamente desde la app. Altamente recomendado para producción.

Para crear un bot de Telegram: buscar @BotFather en Telegram → /newbot → seguir las instrucciones → copiar el token.

2.7 Configuración de instancia

Puertos e identificación de instancia

Nombre de instancia

Identificador interno. Por defecto: saipa. Usá un nombre único si instalás varias instancias en el mismo servidor.

Puerto del engine DEFAULT 8052

Puerto donde escucha el motor de IA. Cambiar solo si 8052 está ocupado.

Puerto de base de datos DEFAULT 5435

Puerto PostgreSQL interno. Cambiar solo si hay conflicto con otra instancia Postgres.

2.8 Método de configuración de Moodle

¿Cómo configurar el plugin en Moodle?

El wizard puede configurar automáticamente los parámetros del plugin en Moodle. Elegir el método según el acceso disponible:

Opción	Descripción	Requisito
A — PHP nativo	Ejecuta `admin/cli/cfg.php` directamente en el servidor	Acceso SSH con `php` en el PATH y ruta al directorio Moodle
B — Docker	Ejecuta el comando dentro del contenedor Moodle via `docker exec`	Moodle debe estar en un contenedor Docker accesible
C — Manual	El wizard muestra los valores al final para configurarlos a mano	Ninguno — siempre disponible como fallback

Opción B (Docker) Es la más común si Moodle corre en Docker. El wizard solicita el nombre del contenedor (por defecto: saipa-moodle).

Si elegís opción C Al finalizar la instalación, el wizard muestra la Engine URL y el Engine Token. Deberás ingresarlos manualmente en Moodle (ver §3.2).

2.9 Deploy automático

Despliegue y verificación

Una vez confirmada la configuración, el wizard ejecuta automáticamente:

Genera docker-compose.yml y .env en el directorio de despliegue (~/saipa-deploy/)
Ejecuta docker compose pull para descargar las imágenes
Ejecuta docker compose up -d para iniciar los servicios
Descarga el modelo LLM seleccionado via Ollama (puede demorar varios minutos)
Descarga e instala los plugins en Moodle (requiere método A o B)
Configura Engine URL y Engine Token en el plugin (métodos A o B)
Ejecuta saipa-doctor para verificar que todo funcione

Tiempo estimado La primera instalación tarda entre 10 y 40 minutos dependiendo de la velocidad de la conexión y el modelo LLM seleccionado. La descarga del modelo es el paso más largo.

4. Verificación de la instalación

4.1 Interpretar el doctor output

Al finalizar la instalación, el wizard muestra una tabla de verificación. Cada check puede tener tres estados:

┌─────────────────────────────┬────────┬──────────────────────────────┐
│ Check                       │ Estado │ Detalle                      │
├─────────────────────────────┼────────┼──────────────────────────────┤
│ saipa-engine /health        │  ✅    │ 200 OK                       │
│ Moodle WS (SAIPA)           │  ✅    │ OK                           │
│ Ollama modelo qwen2.5:14b   │  ✅    │ disponible                   │
│ Telegram bot                │  ✅    │ activo                       │
└─────────────────────────────┴────────┴──────────────────────────────┘

Check	Qué verifica	Si falla
saipa-engine /health	Que el motor de IA esté corriendo y responda con autenticación	Ver §5 — error 1 o error 2
Moodle WS (SAIPA)	Que el token WS sea válido y el plugin esté instalado en Moodle	Ver §5 — error 3
Ollama modelo X	Que el modelo LLM esté descargado y disponible en Ollama	Ver §5 — error 4
Telegram bot	Que el bot responda correctamente (solo si Telegram fue configurado)	Ver §5 — error 5

4.2 Ejecutar doctor manualmente

Podés ejecutar el health check en cualquier momento sin reinstalar:

python3 installer.py doctor

Para especificar un directorio de instalación distinto al predeterminado:

python3 installer.py doctor --dir /ruta/al/deploy

5. Troubleshooting

❌ Error 1 — saipa-engine /health falla con "Connection refused"

El contenedor saipa-engine no está corriendo o el puerto no está disponible.

Verificar que los contenedores estén activos: docker ps | grep saipa
Si no aparecen, levantarlos: cd ~/saipa-deploy && docker compose up -d
Ver logs del engine: docker logs saipa-engine --tail 50
Verificar que el puerto 8052 no esté ocupado: ss -tlnp | grep 8052

❌ Error 2 — saipa-engine /health falla con "HTTP 401 Unauthorized"

El Engine Token en la configuración de Moodle no coincide con el token del engine.

Obtener el token correcto: cat ~/saipa-deploy/.saipa-install.json | grep saipa_api_token
Ingresarlo en Moodle: Admin → SAIPA → Configuración → Engine Token
Purgar cachés de Moodle

❌ Error 3 — Moodle WS falla con "Token inválido"

El token WS ingresado en el wizard no es válido o fue revocado.

Ir a Moodle → Admin → Servicios web → Gestionar tokens
Verificar que el token exista y no esté expirado
Si fue revocado, crear uno nuevo y actualizar el archivo de estado: editar ~/saipa-deploy/.saipa-install.json con el nuevo token
Ejecutar python3 installer.py doctor para verificar

❌ Error 4 — Ollama modelo X no encontrado

El modelo LLM no fue descargado o Ollama no está corriendo.

Verificar que Ollama esté activo: ollama list
Si no está corriendo: ollama serve &
Descargar el modelo manualmente: ollama pull qwen2.5:14b (reemplazar con el modelo elegido)
Verificar que el engine pueda acceder a Ollama: curl http://localhost:11434/api/tags

❌ Error 5 — Telegram bot no responde

Token de Telegram incorrecto o el bot no está en modo polling.

Ver logs del engine: docker logs saipa-engine --tail 30 | grep telegram
Verificar el token en ~/saipa-deploy/.env: campo TELEGRAM_BOT_TOKEN
Reiniciar el engine después de corregir: cd ~/saipa-deploy && docker compose restart saipa-engine
Confirmar que el bot esté en modo polling (no webhook): TELEGRAM_WEBHOOK_URL debe estar vacío

⚠️ Error 6 — docker compose pull falla con "unauthorized"

La imagen del engine en GHCR requiere autenticación o la visibilidad del paquete cambió.

Verificar que la imagen sea pública: docker pull ghcr.io/krl05op11/saipa-engine:latest
Si requiere login: contactar a Schaller & Ponce para obtener credenciales GHCR
Alternativa: hacer login con un PAT de GitHub: echo TOKEN | docker login ghcr.io -u USUARIO --password-stdin

6. Comandos de referencia rápida

Installer CLI

Comando	Descripción
`python3 installer.py install`	Instalación completa guiada desde cero
`python3 installer.py doctor`	Health check de la instalación existente
`python3 installer.py upgrade`	Actualiza imágenes Docker y plugins a la última versión
`python3 installer.py --help`	Muestra todos los comandos disponibles
`python3 installer.py install --dir /ruta`	Especifica directorio de despliegue (default: ~/saipa-deploy)

Docker

Comando	Descripción
`cd ~/saipa-deploy && docker compose up -d`	Inicia todos los servicios
`docker compose down`	Detiene todos los servicios (datos persistentes)
`docker compose restart saipa-engine`	Reinicia solo el motor de IA
`docker logs saipa-engine --tail 50 -f`	Ver logs del engine en tiempo real
`docker logs saipa-postgres --tail 30`	Ver logs de la base de datos
`docker ps`	Estado de todos los contenedores

Archivos importantes

Archivo	Contenido
`~/saipa-deploy/.saipa-install.json`	Estado completo de la instalación (tokens, puertos, modelo)
`~/saipa-deploy/.env`	Variables de entorno del engine (tokens, Telegram, licencia)
`~/saipa-deploy/docker-compose.yml`	Configuración de todos los servicios Docker
`~/saipa-installer/installer_config.yaml`	Configuración del installer (URLs de descarga, versión mínima)

URLs de acceso post-instalación

Panel	URL
Panel docente SAIPA	`https://[moodle-url]/local/saipa/teacher.php`
Panel asesor institucional	`https://[moodle-url]/local/saipa/advisor.php`
Panel EVAL-IA (docente)	`https://[moodle-url]/local/evalia/teacher.php`
Installation Status	`https://[moodle-url]/local/saipa/status.php`
Engine health check	`http://[servidor]:8052/health`

Soporte Si encontrás un problema no cubierto en esta guía, contactar a soporte@schaller-ponce.com.ar con el ID de sesión mostrado al inicio de la instalación (formato: saipa-YYYYMMDD-HHMMSS). Ese ID permite al equipo de soporte revisar los logs de tu instalación en tiempo real.

Schaller & Ponce — Soluciones Educativas con Inteligencia Artificial
soporte@schaller-ponce.com.ar · schaller-ponce.com.ar

Versiones	SAIPA 0.5.1 / EVAL-IA 0.4.8
Moodle requerido	4.4+ o 5.0+ (autodetectado)
Fecha	Abril 2026
Soporte	soporte@schaller-ponce.com.ar
Licencia	Propietaria — uso institucional

Guía de Instalación

SAIPA + EVAL-IA para Moodle

Tabla de Contenidos

1. Antes de empezar

1.1 Requisitos del servidor

1.2 Preparar Moodle

1.3 Obtener el instalador

2. Paso a paso del wizard

2.1 Detección de entorno

2.2 Selección de componentes

2.3 Conexión a Moodle

2.4 Validación de licencia

2.5 Selección del modelo LLM

2.6 Configuración de Telegram

2.7 Configuración de instancia

2.8 Método de configuración de Moodle

2.9 Deploy automático

3. Configuración post-instalación en Moodle

3.1 Verificar el servicio web SAIPA

3.2 Ingresar Engine URL y Engine Token

4. Verificación de la instalación

4.1 Interpretar el doctor output

4.2 Ejecutar doctor manualmente

5. Troubleshooting

6. Comandos de referencia rápida

Installer CLI

Docker

Archivos importantes

URLs de acceso post-instalación