Instalar WebTerminal en IRIS 2024.3

Las versiones recientes de IRIS contienen varios cambios que afectan a la instalación y condiguración de la herramienta OpenSource WebTerminal.

En este articulo, vamos a ver los pasos de instalación, y aprender a buscar y resolver los errores del WebGateway paso a paso.
Esta guía de instalación se ha realizado con la versiones siguientes, las más recientes soportadas a fecha de marzo de 2025:

• Windows 2022 on Internet Information Server (IIS)
• IRIS 2024.3 
• Package Manager 0.9.2
• WebTerminal 4.9.6

IRIS2024.3 es la primera versión de IRIS que no incluye un Servidor Web como parte de la instalación (con la excepción de las versiones "Community" de capacidades más limitadas, que siguen incluyendo un Servidor Web Apache para simplificar el "on-boarding"). En consecuencia, es importante instalar y configurar rimero el Servidor Web IIS antes de proceder a la instalación de IRIS. De esta manera, el instalador de IRIS detecta la presencia del IIS, y propose instalar/configurar un WebGateway que redirige las peticiones Web desde IIS a IRIS. Es posible realizar los pasos en orden inverso (instalar IRIS, despues instalar IIS), pero este requiere la instalación y configuración manual del componente Webgateway de InterSystems.

Guia Rapida para los impacientes

Algunos no querreis leer el articulo entero, resumo aqui los elementos principales de esta guía:

• Instalar IIS primero
  • Añadir protocolo WebSockets
• Instalar IRIS
  • con la opción de modificar la configuración de IIS
• Instalar el ZPM en IRIS con

  • s version="latest" s r=##class(%Net.HttpRequest).%New(),r.Server="pm.community.intersystems.com",r.SSLConfiguration="ISC.FeatureTracker.SSL.Config" d r.Get("/packages/zpm/"_version_"/installer"),$system.OBJ.LoadStream(r.HttpResponse.Data,"c")

• Configurar el ZPM para que acceda a los package del community

  • zpm "enable -community"

• Instalar WebTerminal en el namespace USER

  • zpm "install webterminal"

• Añadir el privilegio Publico de "READ" sobre el recurso %DB_USER 
• en IIS:
  • Añadir las aplicaciones /terminal y /terminalsocket a IIS. Redigirlas para usar el module CSPms del Webgateway, sin verificar si el archivo existe.
• Connectar con 

  http://localhost/terminal/

   

Y Ahora, pasamos a la guía completa con más detalles...

Instalación y configuración de IIS

 Un requerimiento del WebTerminal es el uso de WebSockets, protocolo que no esta habilitado por defecto en IIS.

El Windows Server Manager permite añadir "Roles de Servidor", e instalar IIS:

Se escoge IIS:

Y en las opciones siguientes, se despliega "Aplication Development" para escoger la opción de "WebSockets":

Instalación de IRIS

Se instala IRIS 2024.3. Como ya esta instalado IIS, en un paso del Wizard de instalación, se pregunta si se quiere configurar IIS. Este paso instala y configura el InterSystems WebGateway como Modulo de IIS:

Instalación del Package Manager IPM

El codigo y la documentación de InterSystems Package Manager (IPM anteriormente ZPM)  esta en

https://github.com/intersystems/ipm

Para la instalación, se puede usar el comando descrito en el README.MD de github

s version="latest" s r=##class(%Net.HttpRequest).%New(),r.Server="pm.community.intersystems.com",r.SSLConfiguration="ISC.FeatureTracker.SSL.Config" d r.Get("/packages/zpm/"_version_"/installer"),$system.OBJ.LoadStream(r.HttpResponse.Data,"c")

Y Despues, usar el siguiente comando para permitir el acceso al los Packages de la communidad y habilitar el Package Manager en todos los namespaces

zpm "enable -community"

Instalación del WebTerminal

zpm "install webterminal"

En este paso, se puede validar que el aceso al WebTerminal todavia no esta operacional, ya que IIS + el Webgateway no redirigen la URL /terminal/ a la instancia de IRIS

http://127.0.0.1/terminal/

Abrimos la aplicación de configuración de IIS, para añadir las 2 aplicaciones Web Siguientes

/terminal y /terminalsockets:

A Continuación se debe definir el handler Mapping para esta aplicación, de manera que todas la peticiones estén gestionadas por el WebGateway:

Además, en el "Request Restrictions", es importante permitir las llamadas sin validar que exista un fichero correspondiente. Esto se hace sacando el "check" al "Invoke handler only if request is mapped to:".

Con estos cambios realizados, el IIS ya reenvia las peticiones http://localhost/terminal/ al WebGateway, y la configuración por defecto del Web Gateway redirige estas peticiones a IRIS. 

Se puede validar este paso haciendo una traza de las peticiones del Web gateway mediante la pagina de configuración disponible en http://localhost/csp/bin/system/Module.cxw 

En el menu "View HTTP Trace" s puede ver la petición y la respuesta de IRIS (un Error 401).

En IRIS, se puede investigar la causa del error 401, con las paginas del Audit, que informan de la naturaleza del error interno:

Menu de Portal de Gestión "Administration" / "Security" / "Auditing" / "Configure System Events".

• Para ello, hace falta añadir el "System Event" de "Protect" a la lista de Eventos a registar, y cambiar su estado a "Yes":

Desde el Log de Audit, haciendo una búsqueda sobre los últimos errores, podemos ver 2 errores vinculados con la peticion a /terminal/:

Y los detalles del Error Protect:

La Aplicacion WebTerminal ha sido instalada en el namespace "USER", cuya base de datos esta protegida por el recurso "%DB_USER". El CSP Gateway, cuando establece la conexión e intenta acceder a la aplicación REST /terminal en este namespace, necesita permisos de lectura para responder a las peticiones HTTP Options (preflight requests para CORS).
La solución es dar el permiso publico de Lectura sobre el recurso %DB_USER:

Se hace con el menu "System" /" Security" / "Resources", seleccionando %DB_USER, y añadiendo "Read" como permiso publico.

Y finalmente, se puede volver a hacer la prueba y acceder al terminal, introduciendo usuario y password:

http://localhost/terminal/