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 its handler.
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
python folder. You can even have different python
environments with differents configurations on the same server. To use the
portable python installation in copied 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
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
settings.py of your project. I personally prefer to specify a file that I
explicitely update via a
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
1 2 3 4 5 6 7 8 9
We first clear all the request handlers and then specify that every request
verb="*") should be managed by the
scriptProcessor attribute reproduces the
Full Path and the
Arguments of 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
1 2 3 4 5 6 7 8 9 10 11 12 13
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
1 2 3 4 5 6 7 8 9 10
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:
1 2 3 4
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
Full Path and the
Arguments of the FastCGI
To troubleshoot further, the
fcgi.py command provides several settings to
be put in the
settings.py file :
True, 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 be
AAMMDD is the date,
HHMMSS the time and
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 Django application.
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:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31
With this script, the
Arguments setting of the FastCGI application becomes
d:\sites\esplayer\esplayer\scripts\manage.py fcgi and the
scriptProcessor 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.