Running Python WSGI applications on Microsoft IIS

WSGI – is a web-server to web-application interaction protocol used by many applications written on Python. It is in fact a standard for all Python web-applications. Most popular web frameworks, including Django, CherryPy, Tornado, Flask, Google App Engine support WSGI. The initial version protocol specification can be referenced here – PEP 333. With release of Python 3 there is now updated protocol specification PEP 3333.

To host WSGI-applications with Microsoft IIS 7+ web server there is a unique and free solution – Helicon Zoo. Helicon Zoo in general is an integration platform to run multiple technology stacks in Microsoft IIS web servers.

Installing Helicon Zoo & template WSGI application

To ease process of installing various web server products and technologies we are going to  Microsoft Web Platform Installer. At first let’s download and install Web Platform Installer from it’s official page. Then launch it:

click Options and in «Custom Feeds» box enter http://www.helicontech.com/zoo/feed/ , click «Add feed» and then «Ok»:

Then go to Zoo -> Packages and install Python Hosting Package:

The installation process may take time and will install all required products and engines to host various Python web applications on your server:

After installation is completed your server will be ready to host Python applications simply as any normal IIS web sites. This is really that easy.

Now we are going to create an application to host. There is a collection of project templates in Helicon Zoo feed which you can use as a starting point. Go to Zoo –> Templates and install Python WSGI project.

As you can see, when using WebPI to install project template additional dependencies can be also installed/upgraded. So if you where planning to create one WSGI project you can start right from installing Python WSGI project template instead of installing Python Hosting Package and all required dependencies for this single project will be installed anyway.

After download and install is completed you will be asked to configure WSGI-application. In our case we simply choose a name by which it will be available under Default Web Site:

After all the browser will navigate automatically to the start page for application. This is simple stub page with service information.

How it works?

Helicon Zoo Module is a native IIS 7+ module which acts as a bridge between web server and application on Python, Ruby, Perl, Node.js and other languages. This module uses FastCGI or HTTP protocol to transfer requests from web server to backend application and get responses to the client. This is asynchronous process that utilizes I/O Completion Port technology to provide highest performance and maximum capacity. Additionally Helicon Zoo Module manages backend applications, starts and stops them automatically based on a current service load and overall server resources. It sets appropriate environment for backend applications to run and monitors their health to provide instant and reliable service for all clients.

Configuration directives in web.config file of the IIS web site can be used to change some Helicon Zoo Module settings and configure appropriate environment for the application. Here is web.config example:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <heliconZoo>
      <application name="WSGI.project" >
        <environmentVariables>
          <add name="PYTHONPATH" value="%APPL_PHYSICAL_PATH%;%APPL_PHYSICAL_PATH%\python_modules\Lib\site-packages;%PYTHONPATH%" /> 
          <add name="DEPLOY_FILE" value="deploy.py" />
          <add name="ERROR_LOG_DIR"  value="log" />
          <add name="WSGI_APP" value="wsgi.application" />
        </environmentVariables>
      </application>
    </heliconZoo>
    <handlers>
      <add name="WSGI.project#x86" scriptProcessor="python.2.7.wsgi"
           path="*" verb="*" modules="HeliconZoo_x86" preCondition="bitness32" resourceType="Unspecified" requireAccess="Script" />
      <add name="WSGI.project#x64" scriptProcessor="python.2.7.wsgi"
           path="*" verb="*" modules="HeliconZoo_x64" preCondition="bitness64" resourceType="Unspecified" requireAccess="Script" />
    </handlers>
  </system.webServer>
</configuration>

Here you can see two handlers declaration for 32 or 64 bit IIS processes that will call appropriate version of Helicon Zoo Module. Each handlers sets script processor to “python.2.7.wsgi” which instructs Helicon Zoo to use Python WSGI engine to run this application. Names of the handlers minus #suffix are used to identify additional settings for the application in the <heliconZoo> section. There you can define various environment variables that will be set in backend environment and are used to pass additional parameters to Helicon Zoo Module and application itself. Here are some of possible variables:

• PYTHONPATH – is a path where Python will look for it’s modules and additional files. Here we add current web site physical folder and python_modules\Lib\site-packages folder with modules.
• DEPLOY_FILE – name of the deploy script file that will be called on every application start. Usually there are instructions in this file to install required modules, do database migrations and other deployment things.
• DEPLOY_LOG – a path to the log file where to save deploy script output. If this variable is not set deploy script output will be sent to the client’s browser.
• ERROR_LOG_DIR – a folder where to store various application and error logs. 
• WATCH_FILE_CHANGES_MASK – set this variable to the file mask, like “*.py” and backend application will be restarted when any *.py file inside web site is changed. Useful in development environment. 
• WSGI_APP – a python path to the WSGI application to run. In our case this would be a wsgi.py file in the website root with an application function in it.