Introduction to running WSGI in IRIS

With IRIS 2024+, users can host WSGI applications using Security.Applications. As an example, a user can do something like this

Minimum working example

zn "%SYS"
Kill props
Set props("Description") = "Sample WSGI Application"
Set props("MatchRoles") = ":%All"
Set props("WSGIAppLocation") = "/path/to/flaskapp"
Set props("WSGIAppName") = "myapp"
Set props("WSGICallable") = "app"
Set props("DispatchClass") = "%SYS.Python.WSGI" // important, otherwise will be recognized as CSP application
Set sc = ##class(Security.Applications).Create("/flask", .props)
zw sc

where /path/to/flaskapp directory contains an myapp.py file that reads

from flask import Flask

app = Flask(__name__)

@app.route("/")
def index():
    return "Hello, WSGI!"

Now, go to the URL http(s)://<host>:<port>/<optional-prefix>/flask/. It should show "Hello, WSGI!" in plain text.

Common pitfalls

1. If the URL http(s):///flask/ is not working, check for the trailing slash first, which must be present.

2. Also, when running for the first time, flask needs to be installed for embedded python (not your local OS-level python interpreter). Verify the installation is successful by going to the embedded python shell and run import flask.

3. Finally, read permission of whatever OS user IRIS is assuming must be granted to /path/to/flaskapp/myapp.py and all parent folders.

4. If the error still can't be resolved, check for entries in messages.log. You can also reach out to us by posting an issue

Using IPM to ship WSGI applications for easy install

IPM makes the process easier by
1. copying flask app directory to a place with guaranteed read-access
2. installing relevant python dependencies in a requirements.txt file

Package Example

Here is an example that can be installed easily wherever IPM (v0.7.2+) is installed on IRIS 2024+. Clone this package to a suitable <PACKAGE_ROOT>, and start an IRIS terminal

zn "%SYS"
zpm "load <PACKAGE_ROOT>"

After successful installation, you should be able to visit http(s)://<host>:<port>/<optional-instance-prefix>/my/flask/demo/. In my case, the URL is http://localhost:8080/iris-ml-wsgi/my/flask/demo/ and it reads:

This is a sample WSGI application using Flask!

Hint: you need to install zpm following instructions here first for the zpm command to work.

The module.xml of the above repo is also listed here for quick reference

<?xml version="1.0" encoding="UTF-8"?>
<Export generator="Cache" version="25">
  <Document name="flask-demo.ZPM">
    <Module>
      <Name>flask-demo</Name>
      <Version>1.0.0</Version>
      <Description>This is a demo of a flask application</Description>
      <Keywords>flask</Keywords>
      <Author>
        <Person>Shuheng Liu</Person>
        <Organization>InterSystems</Organization>
        <CopyrightDate>2024</CopyrightDate>
        <License>MIT</License>
        <Notes>notes</Notes>
      </Author>
      <Packaging>module</Packaging>
      <SystemRequirements Version=">=2024.1" />
      <SourcesRoot>src</SourcesRoot>
      <FileCopy Name="src/python/flaskapp/" Target="${libdir}flask-demo/flaskapp/"/>
      <SystemSetting Name="CSP.DefaultFileCharset" Value="UTF-8"/>

      <WSGIApplication
        Url="/my/flask/demo"
        UnauthenticatedEnabled="1"
        Description="Sample WSGI application using Flask"
        MatchRoles=":${dbrole}"
        WSGIAppLocation="${libdir}flask-demo/flaskapp/"
        WSGIAppName="app"
        WSGICallable="app"
       />
    <AfterInstallMessage>Module installed successfully!</AfterInstallMessage>     
    </Module>    
  </Document>
</Export>