IntroPrerequisitesSetupHttpPlatformWFastCGITroubleshootingComparison

Django on IIS

Complete Interactive Tutorial

Deploy Django applications on Internet Information Services using HttpPlatform handler and WFastCGI

Intermediate ~30 min

Introduction

The aim of this tutorial is to deploy Django applications on Internet Information Services (IIS). We'll cover two deployment methods with detailed configuration steps and visual guides.

Note

This tutorial assumes basic knowledge of Django and Python. We'll guide you through the IIS-specific configurations.

Two Deployment Methods:

HttpPlatform Handler

Microsoft's recommended approach for modern Python web applications.

FastCGI Handler (WFastCGI)

Legacy method, no longer actively maintained but still functional.

Prerequisites

Environment

  • Windows Server 2019 (or compatible)
  • IIS with Management Tools
  • Python 3.11+ installed
  • Django 4.1.7+ installed

Required Downloads

1 Install Python & Django

Install Django using pip

pip install Django==4.1.7

Verify Installation

Check Python Version:

python --version

Check Django Version:

py -m django --version

Expected Output:

C:\Users\azureuser>python --version
Python 3.11.2

C:\Users\azureuser>py -m django --version
4.1.7

2 Create Django Application

We'll create a basic Django application following the official Django tutorial. This will be created under C:\sites\site01

Django Project Structure

Understanding the basic Django project structure:

  • mysite/ - Root directory container for your project
  • manage.py - Command-line utility for Django project interaction
  • mysite/settings.py - Settings/configuration for Django project
  • mysite/urls.py - URL declarations (table of contents)
  • mysite/wsgi.py - Entry-point for WSGI-compatible web servers
  • mysite/asgi.py - Entry-point for ASGI-compatible web servers

Project Directory Structure

C:\sites\site01>tree /F
C:.
└───mysite
    │   db.sqlite3
    │   manage.py
    │
    ├───logs
    ├───mysite
    │   │   asgi.py
    │   │   settings.py
    │   │   urls.py
    │   │   wsgi.py
    │   │   __init__.py
    │   │
    │   └───__pycache__
    │           settings.cpython-311.pyc
    │           urls.cpython-311.pyc
    │           wsgi.cpython-311.pyc
    │           __init__.cpython-311.pyc
    │
    └───polls
        │   admin.py
        │   apps.py
        │   models.py
        │   tests.py
        │   urls.py
        │   views.py
        │   __init__.py
        │
        ├───migrations
        │       __init__.py
        │
        └───__pycache__
                urls.cpython-311.pyc
                views.cpython-311.pyc
                __init__.cpython-311.pyc

Test Django Application

py manage.py runserver

This will run the development server at http://localhost:8000

Django Polls Application
Django Polls Application Interface

Important Note:

Create a logs folder in your project directory. This will be used later for IIS logging configuration.

3 IIS Installation & Configuration

Install IIS

Both deployment methods require IIS. You can install it through Server Manager or PowerShell:

Install-WindowsFeature -name Web-Server -IncludeManagementTools

Configure Feature Delegation

Both methods require editing Handler Mappings, which by default has read-only permissions. We need Read/Write access:

Path: IIS Manager → Server Level → Feature Delegation → Handler Mappings → Read/Write

IIS Feature Delegation
IIS Feature Delegation Settings

Create Two Sites

We'll create two separate sites to demonstrate both deployment methods:

Site01 - HttpPlatform

  • Port: 8001
  • Path: C:\sites\site01
  • Method: HttpPlatform Handler

Site02 - WFastCGI

  • Port: 8002
  • Path: C:\sites\site02
  • Method: WFastCGI Handler

Method 1: HttpPlatform Handler (Recommended)

Why HttpPlatform Handler?

Microsoft recommends HttpPlatform handler as it's actively maintained and provides better process management for Python applications.

Step 1: Download HttpPlatform Handler

Download and install the HttpPlatformHandler v1.2 from Microsoft:

Download HttpPlatformHandler

What it does:

  • Process management of HTTP Listeners
  • Proxy requests to the managed process
  • Works with any process that can listen on a port (Python, Node.js, etc.)

Step 2: Configure httpPlatform Settings

Navigate to: IIS Manager → Sites → Site01 → Configuration Editor → system.webServer/httpPlatform

Setting Value Description
processPath C:\Python311\python.exe Path to Python executable
arguments C:\sites\site01\mysite\manage.py runserver %HTTP_PLATFORM_PORT% Django management command with dynamic port
stdoutLogEnabled true Enable logging output
stdoutLogFile C:\sites\site01\mysite\logs Path for log files

Step 3: Configure Environment Variables

Navigate to: IIS Manager → Sites → Site01 → Configuration Editor → appSettings

Required Environment Variables:

PYTHONPATH = C:\sites\site01\mysite
WSGI_HANDLER = django.core.wsgi.get_wsgi_application()
DJANGO_SETTINGS_MODULE = mysite.settings

Step 4: Add Handler Mapping

Navigate to: IIS Manager → Sites → Site01 → Handler Mappings → Add Module Mapping

IIS Handler Mappings
IIS Handler Mappings Configuration

Handler Mapping Settings:

  • Request path: *
  • Module: httpPlatformHandler
  • Name: MyPyHandler (or any name)

Important: Click "Request Restrictions" and uncheck "Invoke handler only if request is mapped to"

Step 5: Complete web.config

Your final web.config should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <httpPlatform processPath="C:\Python311\python.exe"
                      arguments="C:\sites\site01\mysite\manage.py runserver %HTTP_PLATFORM_PORT%"
                      stdoutLogEnabled="true"
                      stdoutLogFile="C:\sites\site01\mysite\logs">
            <environmentVariables>
                <environmentVariable name="SERVER_PORT" value="%HTTP_PLATFORM_PORT%" />
            </environmentVariables>
        </httpPlatform>
        <handlers>
            <add name="MyPyHandler" path="*" verb="*" modules="httpPlatformHandler" resourceType="Unspecified" />
        </handlers>
    </system.webServer>
    <appSettings>
        <add key="PYTHONPATH" value="C:\sites\site01\mysite" />
        <add key="WSGI_HANDLER" value="django.core.wsgi.get_wsgi_application()" />
        <add key="DJANGO_SETTINGS_MODULE" value="mysite.settings" />
    </appSettings>
</configuration>

Test Your Configuration

Navigate to http://localhost:8001/polls to test your Django application running on IIS with HttpPlatform handler.

Method 2: WFastCGI Handler (Legacy)

Legacy Method

WFastCGI is no longer actively maintained by Microsoft, but still functional for existing deployments.

Step 1: Install WFastCGI

pip install wfastcgi

Step 2: Install CGI Module for IIS

Install-WindowsFeature -name Web-CGI

Close and reopen IIS Manager to see the new FastCGI module.

Step 3: Configure FastCGI Application

Navigate to: IIS Manager → Server Level → FastCGI → Add Application

FastCGI Application Settings
FastCGI Application Configuration

FastCGI Settings:

  • Full Path: C:\Python311\python.exe
  • Arguments: C:\Python311\Lib\site-packages\wfastcgi.py

Step 4: Add Handler Mapping

Navigate to: IIS Manager → Sites → Site02 → Handler Mappings → Add Module Mapping

Handler Mapping Settings:

  • Request Path: *
  • Module: FastCgiModule
  • Executable: C:\Python311\python.exe|C:\Python311\Lib\site-packages\wfastcgi.py
  • Name: MyPyHandler2 (or any name)

Important: Uncheck "Invoke handler only if request is mapped to" in Request Restrictions.

Step 5: Configure App Settings

Navigate to: IIS Manager → Sites → Site02 → Configuration Editor → appSettings

PYTHONPATH = C:\sites\site02\mysite
WSGI_HANDLER = django.core.wsgi.get_wsgi_application()
DJANGO_SETTINGS_MODULE = mysite.settings

Step 6: Complete web.config

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <handlers>
            <add name="MyPyHandler2" path="*" verb="*" modules="FastCgiModule"
                 scriptProcessor="C:\Python311\python.exe|C:\Python311\Lib\site-packages\wfastcgi.py"
                 resourceType="Unspecified" requireAccess="Script" />
        </handlers>
    </system.webServer>
    <appSettings>
        <add key="PYTHONPATH" value="C:\sites\site02\mysite" />
        <add key="WSGI_HANDLER" value="django.core.wsgi.get_wsgi_application()" />
        <add key="DJANGO_SETTINGS_MODULE" value="mysite.settings" />
    </appSettings>
</configuration>

Step 7: FastCGI Configuration File

The FastCGI section is stored in C:\Windows\System32\inetsrv\Config\applicationHost.config:

<system.webServer>
    <fastCgi>
        <application fullPath="C:\Python311\python.exe"
                     arguments="C:\Python311\Lib\site-packages\wfastcgi.py"
                     monitorChangesTo=""
                     stderrMode="ReturnStdErrIn500"
                     maxInstances="4"
                     idleTimeout="300"
                     activityTimeout="30"
                     requestTimeout="90"
                     instanceMaxRequests="200"
                     signalBeforeTerminateSeconds="0"
                     protocol="NamedPipe"
                     queueLength="1000"
                     flushNamedPipe="false"
                     rapidFailsPerMinute="10" />
    </fastCgi>
</system.webServer>

Test Your Configuration

Navigate to http://localhost:8002/polls to test your Django application running on IIS with WFastCGI handler.

Troubleshooting & Tips

Common Issues

  • • 500 Internal Server Error - Check logs folder
  • • Handler not found - Verify module installation
  • • Python path errors - Check PYTHONPATH setting
  • • Port conflicts - Ensure ports 8001/8002 are free
  • • Permission issues - Check IIS app pool identity

Best Practices

  • • Use HttpPlatform for new deployments
  • • Always enable logging for debugging
  • • Create separate app pools for each site
  • • Monitor performance and resource usage
  • • Keep Python and Django updated

Log File Locations

# HttpPlatform logs
C:\sites\site01\mysite\logs\

# IIS logs
C:\inetpub\logs\LogFiles\

# Windows Event Logs
Event Viewer → Windows Logs → Application

Performance Optimization

  • FastCGI: Adjust maxInstances and recycling settings
  • HttpPlatform: Consider using production WSGI servers like Gunicorn
  • Static Files: Configure IIS to serve static files directly
  • Caching: Implement appropriate caching strategies

Method Comparison

Feature HttpPlatform Handler WFastCGI
Maintenance Status ✓ Actively maintained ✗ No longer maintained
Microsoft Recommendation ✓ Recommended ~ Legacy support
Setup Complexity ✓ Simpler configuration ~ More complex setup
Process Management ✓ Better process handling ~ Basic process management
Performance ✓ Good for development/testing ✓ Can be optimized for production

Conclusion

You now have two working methods to deploy Django applications on IIS. Both approaches have their merits:

Choose HttpPlatform Handler if:

  • • Starting a new deployment
  • • Want Microsoft's recommended approach
  • • Need simpler configuration
  • • Prefer active maintenance and support

Choose WFastCGI if:

  • • Working with existing deployments
  • • Need specific FastCGI features
  • • Have experience with CGI configuration
  • • Comfortable with legacy systems

Recommendation: For production deployments, consider using dedicated WSGI servers like Gunicorn or uWSGI behind IIS as a reverse proxy for better performance and scalability.