== Goals == Getting Django to run on Windows, with pages served by IIS, and a SQL Server backend. Assume Windows Server 2003, IIS 6 and SQL Server 2005 where no versions are specified. You should already have Windows, IIS and SQL installed and working before following this guide. '''Note''': As of PyISAPIe version 1.0.4, this works with Python 2.5. The provided handler works with the current (1-11-08) CVS version of Django. '''Note2''': PyISAPIe also provides a WSGI adapter that may work with earlier versions of Django. Refer to the new release and docs: http://pyisapie.sourceforge.net/ === Steps === * Install Python * Install PyISAPIe - an extension for IIS to connect Python with IIS * Install Django and connect Django to PyISAPIe * ADODB-API - the Python / SQL Server driver * Configure Django to look at SQL Server * Test, celebrate == Install Python == A simple download and install for this bit, so open http://www.python.org/ and look for "Quick Links" -> "Windows Installer" in the menu on the left. Download and run it, following the wizard steps until it is complete. == Install PyISAPIe - an ISAPI extension for IIS == PyISAPIe is an IIS extension that loads the Python interpreter into memory while IIS is running, and uses it to serve page requests - it avoids the CGI overhead of restarting Python for every request. It does mean that some Django files will be cached and you wont see changes while testing your Django site until you restart the Python process. With IIS 6 you have to right-click on the application pool running your services and select 'recycle' for changes to take. Previous versions of IIS will need the whole IIS service to be restarted. I will assume you are using c:\python25 as the folder where Python is installed, but please change these where necessary for your setup. If you have problems with PyISAPIe, check out the [http://groups.google.com/group/pyisapie?hl=en PyISAPIe Google Group] for support. === Setting up Files === * Go to http://pyisapie.sourceforge.net/ and download it (look in the menu on the right, under "Links" for a download link). Unzip the archive to c:\pyisapie. * Edit the properties -> security settings of c:\pyisapie\PyISAPIe.dll, add "Network Service" and tick "read" permission. (So IIS can use it). * Go to c:\pyisapie\source\PyISAPIe\Python\ and copy the entire Http folder to c:\python25\lib\site-packages. '''''Note:''' the Http folder is case sensitive. Saving in 'http' (or any other variation) will not work [SF]''. === Setting up IIS === You don't have to create a virtual directory - you can do this with the root folder. If you do use a virtual directory, say /myfolder, then only urls starting with /myfolder will be handled by PyISAPIe. If you use the root folder, all URLs will be handled by PyISAPIe, and you risk anything else on the site being inaccessible afterwards if you're not careful. * Open the IIS Management Console, and create a new virtual directory, and allow executing ISAPI extensions when prompted by the wizard. ==== Multiple Django Installations on IIS ==== You can only run multiple instances of Django on IIS 6.0 if you use a separate instance of PyISAPIe for each Django instance. This is accomplished by setting up an IIS Application Pool for each PyISAPIe/Django instance that needs to be run. It would be great if multiple instances of Django could run under a single PyISAPIe instance. Please encourage the Django developers to work on this issue and/or contribute a fix yourself. You can find more information about this issue here: * [http://code.djangoproject.com/ticket/2039 Trac Ticket: Provide a way to use django under IIS] * [http://groups.google.com/group/pyisapie/browse_thread/thread/b67e861c85e1b26a?hl=en PyISAPIe Group: Multiple PyISAPIe Instances (for Django)] * [http://groups.google.com/group/django-developers/browse_thread/thread/dfd69014daa36672 Developers Group: IIS, pyisapie, and DJANGO_SETTINGS_MODULE] * [http://groups.google.com/group/pyisapie/web/multiple-instances-of-django-on-iis-with-pyisapie?hl=en A brief tutorial on getting multiple instances of Django running on IIS (including directory structure diagram)] Multiple instances of Django on IIS 5.1 is not currently possible. ==== IIS 7 ==== * Add the PyISAPIe handler by selecting "Handler Mappings ==> Add Script Map" with the following settings: * Request Path = * * Executable = Path to the PyISAPIe.dll * Name = PyISAPIe (name can be anything) * Also, be sure that the PyISAPIe handler is higher than the StaticFile handler by clicking "View Ordered List" and reordering as needed. ==== IIS 6 ==== * View the properties of the new folder and click on the "configuration" button (if it's greyed out, click 'create' first), then add a new wildcard extension (the lower box), locate the pyisapie.dll file and untick the "check that file exists" box. * In the IIS Manager, go to the "Web Service Extensions" section, and right click -> add new web service extension. * Give it a name (it doesn't matter what), add the pyisapie.dll fill as a required file and check the box to set the extension status to allowed. ==== IIS 5 ==== * IIS 5.x doesn't support wildcard application maps, at least not through the configuration interface. On IIS 5, the procedure is as follows: * Right Click on virtual directory and choose "properties" * Ensure "Execute Permissions" is set to "Scripts and Executables" * Click "Configuration" (opposite "Scripts and Executables") * On "App Mappings" tab, select "Add" * For Executable, browse to pyisapie.dll (needs full path if you enter manually) * For extension enter ''*'' (this will redirect all requests to pyisapi) * ''Using star DOES NOT work in IIS 5, you must specify an extension. [pjs]'' * ''You should probably limit the verbs allowed; I left as ''all'' since it was for internal use.'' * Untick the "check that file exists" box. * 'OK' to close all the open dialogs. That's it installed. In c:\pyisapie\source\PyISAPIe\Python\examples folder is a file called Info.py. Copy this to your new virtual directory folder, and then try and view http://site/Info.py to test it. It should work. If it doesn't, when you find out why, please come back and explain what happened and how you fixed it. ;) If you have a 64-bit server, and you want to use 32-bit Python and PyISAPIe (otherwise you have to compile your own PyISAPIe.dll) you may need to: * Create a new application pool, set it to 32-bit mode, create an application instead of a virtual directory, and set your application to use that pool (http://www.timvasil.com/blog14/post/2007/11/Run-a-32-bit-ISAPI-DLL-on-64-bit-IIS-7.aspx) * If you then get Error 500 due to (error number 2147942593) try removing all AboMapperCustom-* handlers from the applications handlers/mappings (http://social.msdn.microsoft.com/Forums/en-US/sharepointdevelopment/thread/1131026f-7d8b-4e88-8d2c-398b12f4336d/) ==== IIS Troubleshooting ==== * "Import Error: couldn't locate module Http.Isapi" -- see [http://groups.google.com/group/django-users/browse_thread/thread/1d2cbd681f2b6f7f Users Group: IIS 6 PyISAPIe problems] == Django == '''Text below saved in hope of an update to PyISAPIe:'''[[BR]] ''If you want to keep up with the latest Django development version, you will need to download and install a subversion client for Windows, e.g. [http://tortoisesvn.tigris.org/ Tortoise SVN], install it, then create a new folder somewhere. Right click on the folder, and choose "SVN Checkout". Give the URL of the repository as: http://code.djangoproject.com/svn/django/trunk/ and click OK.)'' ''Otherwise, just download the latest Django release from the main site, and extract the archive to a folder, e.g. c:\python25\django\.'' === Installing Django === Drop to a command prompt (start -> run -> "cmd" -> OK), change to your Python folder and install Django. Example: {{{ c:\> cd python25\django c:\python25\django> python setup.py install }}} NB: You will probably need to do some messing around with paths and such to make this work neatly. I'm afraid I'm leaving that to you for now, because I don't have clear steps. If you know any, please put them here. Without doing that you can still test the Django install, but will need a full path to django-admin.py: {{{ c:\> md test c:\> cd test c:\test> d:\Python25\django\django\bin\django-admin.py startproject proj c:\test> cd proj c:\test\proj> python manage.py runserver Validating models... 0 errors found. Django version 0.95 (post-magic-removal), using settings 'proj.settings' Development server is running at http://127.0.0.1:8000/ Quit the server with CTRL-BREAK. }}} Now open a web browser, and visit the site. It should serve a neat page to you. === Linking Django to PyISAPIe === Next, you must follow the readme.txt in the PyISAPIe examples\django folder, basically copy two files into specific folders. Then edit them a bit in order to fit your needs. * Put Isapi.py in c:\python25\lib\site-packages\Http folder. According to the example given above, you'll make the following changes to it: {{{ # Add these two lines, and python will import DJANGO_SETTINGS_MODULE with no problem import sys sys.path.append(r'c:\test') # Indicate the settings module of your project os.environ["DJANGO_SETTINGS_MODULE"] = "proj.settings" }}} * Put pyisapie.py in c:\python25\lib\site-packages\Django-xyz-123.egg\django\core\handlers folder. === Serving Django with IIS === Supposed that you have successfully settled everything above, and pointed the virtual directory /myfolder to c:\test folder, we'll now make a Hello World page in Django. * Create a file called ''helloworld.py'' in c:\test\proj folder with the following content: {{{ from django.http import HttpResponse def index(request): return HttpResponse("Hello world!") }}} * Modify ''urls.py'' in c:\test\proj folder, so you get the url "dispatched": {{{ from django.conf.urls.defaults import * urlpatterns = patterns('', # Example: # (r'^newtest/', include('proj.apps.foo.urls.foo')), (r'^.*$', 'proj.helloworld.index'), # Uncomment this for admin: # (r'^admin/', include('django.contrib.admin.urls')), ) }}} You have everything you need to have Django running from IIS. Now visit http://site/myfolder/ to take a look. Notice that you don't need to manually start a Django server. == Known Issues == * On IIS 5, you have to use the console command "iisreset" for code changes to take effect. Just restarting the website in ''IIS Management Console'' has no use. How about IIS 6? (20070304/henrik: - same for iis6 on win2k3) * ''NOT true for IIS6: right-click on the application pool your site is using and select "Recycle." [pjs]'' * ''For debugging purposes in IIS6 you could set "Recycle worker process (number of requests)" = 1 in your application pool properties so you don't need to "Recycle" all the time. NOT recommended for production usage. [ta]'' * ''I had to create a "media" virtual directory for the stylesheets, etc, at the root of my IIS directory tree (urgh) with read permissions to get the admin site to load styles. Looking at the source for the admin page in my browser, the stylesheet link is absolute (/media/...) [rnm]'' == Configure Django for SQL Server == There are two external Django database backends for SQL Server: * http://code.google.com/p/django-mssql/ * http://code.google.com/p/django-pyodbc/ Both of these projects are tracking the Django 1.0 release. Issues with those projects should be reported in their corresponding issue trackers. == Credits == * http://thinkhole.org/wp/2006/04/03/django-on-windows-howto/ for the Django on Windows with Postgres/Apache guide, from which I took some parts of the django-on-windows setup. == Additional Info == * For a Chinese translation, please try this [http://wiki.woodpecker.org.cn/moin/D4I] * Several links appeared to be broken, so I created an alternative installation approach. Details here: [http://www.kelvinism.com/howtos/using-django-sql-server-iis/] * Up-to-date 1.1RC4 installation notes (DB oracle) : http://groups.google.com/group/pyisapie/web/django-1-1-iis6-pyisapie-1-1-rc4-cx-oracle