Running Django Under Windows With Iis Using Fcgi
Update: The configuration process described in this post can be achieved with only one management command if you install the django-windows-tools application.
Windows is probably not the best production environment for Django but sometimes one doesn’t have the choice. In that case, a few options aleardy exist, most notably the one developed by helicontech that relies on Microsoft’s Web Platform Installer. This solution, which is described here, relies on the installation of a specific native Handler developed by Helicontech.
This handler manages the communication between IIS and the Django application
through the FastCGI protocol with the help of a little
python script that bridges FastCGI to WSGI. This script is derived from the
Allan Saddi flup package that is already used by
Django in the
manage.py runfcgi command. The flup package doesn’t work under
Windows and Helicontech has made the necessary adaptations to make it work with
Since its version 7, IIS does however support FastCGI natively, so the use of a specific handler to support Django is not needed. This post describes how to configure and run a Django application with the native FastCGI IIS handler. For that, I have myself adapted the Helicontech FastCGI to WSGI script to make it a Django management command.
But before that, to run Django you will need to have python on your server. If
like me for some reason it is uneasy for you to run a software installer on your
server, a good choice is to use
Portable Python. With it, you can install and
configure your python environment on your development or staging server and
install it in your production server(s) by just copying over the
folder. You can even have different python environments with differents
configurations on the same server. To use the portable python installation in
d:\python from a command line window, juste type:
And then python and its commands are available from the command line:
Another advantage of Portable Python is that it comes already bundled with The Python for Windows extensions (a.k.a. pywin32) and Django.
Adding FastCGI to the project
In our example, the Django project will be named
esplayer and will be
d:\sites\esplayer. Please note that this configuration has been
tested on Windows 2008 Server R2.
Take the fcgi.py file and copy it in the
management\commands directory of one of your project applications so that the
manage.py help fcgi command returns you:
Configure the FastCGI application on IIS
The next step is to configure the FastCGI Application on IIS. FastCGI is available whenever you have installed the CGI feature on your IIS installation. Run the server manager and go to the IIS role and configuration. Select your website. You should see a FastCGI Settings icon:
Double click on it and select the Add application action. Enter the following parameters:
Full Path, enter the path to your python executable.
Arguments, enter the command line for running our fcgi command, i.e.
d:\sites\esplayer\esplayer\manage.py fcgi --pythonpath=d:\sites\esplayer --settings=esplayer.settings. The
settingsarguments are needed to be path independent (more on this later).
The other arguments are optional but you should review them to enter sensible
Monitor changes to file setting is particularly interesting. It
will allow you to specify the path of a file that will trigger a restart of the
application whenever it is modified. You can enter the path to the
of your project. I personally prefer to specify a file that I explicitely update
Create the website and configure it to use the FastCGI application
Once we have our FastCGI application configured, we need a web site to make use of it. For it, we create a website pointing to our Django project:
To make the website use our FastCGI application, we create the following
web.config file in the root of our project (here d:\sites\esplayer\esplayer):
We first clear all the request handlers and then specify that every request
verb="*") should be managed by the
FastCgiModule module. The
scriptProcessor attribute reproduces the
Full Path and the
our FastCGI application separated by
|. It allows the module to identify the
FastCGI application to which the requests will be routed.
With the preceding
web.config configuration, all the requests are routed to
the Django application. However, we want the static files of our application to
be managed by IIS itself. To do that, we first configure Django to collect the
static files in the
static subdirectory of our project. For that, we have the
following configuration in our
The project wide defined static files are located in the
directory. All the static files are collected in the
static directory by
running the following command:
local_static directory we put the following
Which basically inverts the
web.config file or the root of the project by
clearing all the handlers and serving all requests only as static files. When
collected, this file will go in the
static directory and will instruct IIS
that all requests below the path
/static should be served as static files.
Website creation automation
The website creation that is described in the previous sections can be automated with the following script that must be run as an administrator:
The four commands run in the script do the following actions:
- Create the FastCGI application.
- Create the site application pool.
- Create the website.
- Add the created website to the application pool.
Testing and troubleshooting
After the configuration, the website should be available through IIS. If this is
not the case, you will probably get a
The first thing to do is to check that the website is available outside of IIS by running it with the command:
And accessing it on
http://localhost:8000. If the application works as a
standalone Django application, the most common cause of error is a
misconfiguration of either the FastCGI application or the root
file. You need to be sure that the The
scriptProcessor attribute of the
Full Path and the
Arguments of the FastCGI application.
To troubleshoot further, the
fcgi.py command provides several settings to be
put in the
settings.py file :
instructs the command to create a log file in the path pointed by
FCGI_LOG_PATH is not defined, the log file will be created
in the project root directory. The file name name pattern of the log file will
fcgi_AAMMDD_HHMMSS_XXXX.log, in which
AAMMDD is the date,
XXXX the FastCGI application process number. If
DEBUG is set to
True in the settings, the log file will contain the Django debug logs. The
FCGI_DEBUG setting (default
False), when set to
True, will output in the
log file information about the FCGI protocol transfers between IIS and the
Easing the FastCGI configuration
It is somewhat painful to have to specify the
parameters both in the FastCGI configuration and in the
web.config file. To
avoid entering them each time, I have created a
manage.py script in the
scripts subdirectory of the project root that auto configures itself. Here
is the source of the file:
With this script, the
Arguments setting of the FastCGI application becomes
d:\sites\esplayer\esplayer\scripts\manage.py fcgi and the
attribute in the
web.config file becomes
Once this configuration is done on a project and a server, replicating it across multiple servers is easy as the only configuration not part of the project is the one of the FastCGI application. Most configuration files are ported from server to server with the source code of the project.
However, the first creation and configuration could benefit from having some management commands dedicated to it. These would be part, along with the fcgi.py command, of a specific Django application that could be added to any project.
Furthermore, some of you may have noted that having the website point to the root of the Django project is not mandatory. Thus the Django project itself could be part of the python installation itself and deployed by running a Django management command.