/docs/howto/deployment/modwsgi.txt

  1==========================================
  2How to use Django with Apache and mod_wsgi
  3==========================================
  4
  5Deploying Django with Apache_ and `mod_wsgi`_ is the recommended way to get
  6Django into production.
  7
  8.. _Apache: http://httpd.apache.org/
  9.. _mod_wsgi: http://code.google.com/p/modwsgi/
 10
 11mod_wsgi is an Apache module which can be used to host any Python application
 12which supports the `Python WSGI interface`_, including Django. Django will work
 13with any version of Apache which supports mod_wsgi.
 14
 15.. _python wsgi interface: http://www.python.org/dev/peps/pep-0333/
 16
 17The `official mod_wsgi documentation`_ is fantastic; it's your source for all
 18the details about how to use mod_wsgi. You'll probably want to start with the
 19`installation and configuration documentation`_.
 20
 21.. _official mod_wsgi documentation: http://code.google.com/p/modwsgi/
 22.. _installation and configuration documentation: http://code.google.com/p/modwsgi/wiki/InstallationInstructions
 23
 24Basic configuration
 25===================
 26
 27Once you've got mod_wsgi installed and activated, edit your ``httpd.conf`` file
 28and add::
 29
 30    WSGIScriptAlias / /path/to/mysite/apache/django.wsgi
 31
 32The first bit above is the url you want to be serving your application at (``/``
 33indicates the root url), and the second is the location of a "WSGI file" -- see
 34below -- on your system, usually inside of your project. This tells Apache
 35to serve any request below the given URL using the WSGI application defined by that file.
 36
 37Next we'll need to actually create this WSGI application, so create the file
 38mentioned in the second part of ``WSGIScriptAlias`` and add::
 39
 40    import os
 41    import sys
 42
 43    os.environ['DJANGO_SETTINGS_MODULE'] = 'mysite.settings'
 44
 45    import django.core.handlers.wsgi
 46    application = django.core.handlers.wsgi.WSGIHandler()
 47
 48If your project is not on your ``PYTHONPATH`` by default you can add::
 49
 50    path = '/path/to/mysite'
 51    if path not in sys.path:
 52        sys.path.append(path)
 53
 54just below the ``import sys`` line to place your project on the path. Remember to
 55replace 'mysite.settings' with your correct settings file, and '/path/to/mysite'
 56with your own project's location.
 57
 58.. _serving-files:
 59
 60Serving files
 61=============
 62
 63Django doesn't serve files itself; it leaves that job to whichever Web
 64server you choose.
 65
 66We recommend using a separate Web server -- i.e., one that's not also running
 67Django -- for serving media. Here are some good choices:
 68
 69    * lighttpd_
 70    * Nginx_
 71    * TUX_
 72    * A stripped-down version of Apache_
 73    * Cherokee_
 74
 75If, however, you have no option but to serve media files on the same Apache
 76``VirtualHost`` as Django, you can set up Apache to serve some URLs as
 77static media, and others using the mod_wsgi interface to Django.
 78
 79This example sets up Django at the site root, but explicitly serves
 80``robots.txt``, ``favicon.ico``, any CSS file, and anything in the
 81``/static/`` and ``/media/`` URL space as a static file. All other URLs
 82will be served using mod_wsgi::
 83
 84    Alias /robots.txt /usr/local/wsgi/static/robots.txt
 85    Alias /favicon.ico /usr/local/wsgi/static/favicon.ico
 86
 87    AliasMatch ^/([^/]*\.css) /usr/local/wsgi/static/styles/$1
 88
 89    Alias /media/ /usr/local/wsgi/media/
 90    Alias /static/ /usr/local/wsgi/static/
 91
 92    <Directory /usr/local/wsgi/static>
 93    Order deny,allow
 94    Allow from all
 95    </Directory>
 96
 97    <Directory /usr/local/wsgi/media>
 98    Order deny,allow
 99    Allow from all
100    </Directory>
101
102    WSGIScriptAlias / /usr/local/wsgi/scripts/django.wsgi
103
104    <Directory /usr/local/wsgi/scripts>
105    Order allow,deny
106    Allow from all
107    </Directory>
108
109.. _lighttpd: http://www.lighttpd.net/
110.. _Nginx: http://wiki.nginx.org/Main
111.. _TUX: http://en.wikipedia.org/wiki/TUX_web_server
112.. _Apache: http://httpd.apache.org/
113.. _Cherokee: http://www.cherokee-project.com/
114
115.. More details on configuring a mod_wsgi site to serve static files can be found
116.. in the mod_wsgi documentation on `hosting static files`_.
117
118.. _hosting static files: http://code.google.com/p/modwsgi/wiki/ConfigurationGuidelines#Hosting_Of_Static_Files
119
120.. _serving-the-admin-files:
121
122Serving the admin files
123=======================
124
125Note that the Django development server automagically serves the static files
126of the admin app, but this is not the case when you use any other server
127arrangement. You're responsible for setting up Apache, or whichever media
128server you're using, to serve the admin files.
129
130The admin files live in (:file:`django/contrib/admin/static/admin`) of the
131Django distribution.
132
133We **strongly** recommend using :mod:`django.contrib.staticfiles` to handle
134the admin files, but here are two other approaches:
135
136    1. Create a symbolic link to the admin static files from within your
137       document root.
138
139    2. Or, copy the admin static files so that they live within your Apache
140       document root.
141
142Details
143=======
144
145For more details, see the `mod_wsgi documentation on Django integration`_,
146which explains the above in more detail, and walks through all the various
147options you've got when deploying under mod_wsgi.
148
149.. _mod_wsgi documentation on Django integration: http://code.google.com/p/modwsgi/wiki/IntegrationWithDjango