Running a Django app on Windows IIS

Introduction

In most cases, I would recommend using a 'unix' OS and nginx for running your Django application. However, there are times that it's necessary for you to use Windows and IIS.

This is a compilation of a few tutorials and Stack Overflow answers. I've referenced them at the section in the bottom.

Preqrequistes:

I assume the following has already been setup:

  • IIS 7+ with the CGI module is installed on your machine
  • Python 2.7+/3.4+ with pip and django are already installed
  • You already have an example Django application and know how to edit it

If you don't have IIS installed:

If you don't have a Django application created and don't know how, then I suggest reading through Django's documentation which is not only very documented, but also has quite a few useful tutorials. Note: I've linked to the 'dev' branch of documentation to make this tutorial a little more relevant over time. However, it's important you use the documentation of the actual version of Django you have installed.

Note: This guide works for native and environment based Python installation. I personally used an Anaconda Environment without any issues. It's assumed from the rest of this guide, that you're working in this environment.

Installation and Setup

There are two major steps to take when installing and setting up Django to be used on IIS.

  1. Installing and enabling wfastcgi
  2. Configuring IIS for Django

Installing and enabling wfastcgi

Summary (tl;dr)

  1. pip install wfastcgi
  2. wfastcgi-enable

Detailed Explanation

First off, we need to install wfastcgi using pip (or you preference of installation method):

    pip install wfastcgi

wfastcgi was created by the Python Tools for Visual Studio people, but PTVS isn't required. If you find any issues with wfastcgi you can file a report on their Github repo.

After installing you need to enable wfastcgi you need to enable it:

    wfastcgi-enable

You may need to use the full file path:

    <path to python install>\scripts\wfastcgi-enable

Configuring IIS for Django

Summary (tl;dr)

  1. Add Handler Mapping
  2. Set Root folder for IIS Site

A file called web.config should be created in root folder of you Django Site (same location as your manage.py file). Here's a template:

<?xml version="1.0" encoding="UTF-8"?>
    <configuration>
        <system.webServer>
            <handlers>
                <add name="Python FastCGI" 
                     path="*" 
                     verb="*" 
                     modules="FastCgiModule" 
                     scriptProcessor="<Path to Python>\python.exe|<Path to Python>\lib\site-packages\wfastcgi.py" 
                     resourceType="Unspecified" 
                     requireAccess="Script"/>
            </handlers>
        </system.webServer>
        <appSettings>
            <add key="WSGI_HANDLER" value="<WSGI_HANDLER based on Django Version>" />
            <add key="PYTHONPATH" value="<Path to Django App>" />
            <add key="DJANGO_SETTINGS_MODULE" value="<Django App>.settings" />
        </appSettings>
    </configuration>

Parameters:

WSGI_HANDLER: this configuration is dependent on the version of Django you're running:

  • Django 1.7+: django.core.wsgi.get_wsgi_application()
  • Otherwise: django.core.handlers.wsgi.WSGIHandler()

Example web.config:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add name="Python FastCGI" 
                 path="*" 
                 verb="*" 
                 modules="FastCgiModule" 
                 scriptProcessor="c:\anaconda3\envs\django\python.exe|c:\anaconda3\envs\django\lib\site-packages\wfastcgi.py" 
                 resourceType="Unspecified" 
                 requireAccess="Script"/>
        </handlers>
    </system.webServer>
    <appSettings>
        <add key="WSGI_HANDLER" value="django.core.wsgi.get_wsgi_application()" />
        <add key="PYTHONPATH" value="C:\inetpub\wwwroot\HelloWorld" />
        <add key="DJANGO_SETTINGS_MODULE" value="HelloWorld.settings" />
    </appSettings>
</configuration>

Troubleshooting

Here are a few issues that I can into while setting this up.

django.core.exceptions.AppRegistryNotReady: Apps aren't loaded yet.

If you get this error, then that means you're probably using the wrong WSGI_HANDLER option for your version of Django.

Exception: WSGI_HANDLER env var must be set

This means that your web.config doesn't have the correct app keys configured and is missing the WSGI_HANDLER environment variable.

Static Files

Within the folder that you store your static files you'll need to add this

    <?xml version="1.0" encoding="UTF-8"?>
<configuration>
  <system.webServer>
    <handlers>
      <remove name="Python FastCGI" />
    </handlers>
  </system.webServer>
</configuration>

References

Comments

comments powered by Disqus