<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>How to use Django with Apache and mod_python — Django 1.4.5 documentation</title>
<link rel="stylesheet" href="../../_static/default.css" type="text/css" />
<link rel="stylesheet" href="../../_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: '../../',
VERSION: '1.4.5',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</script>
<script type="text/javascript" src="../../_static/jquery.js"></script>
<script type="text/javascript" src="../../_static/underscore.js"></script>
<script type="text/javascript" src="../../_static/doctools.js"></script>
<link rel="top" title="Django 1.4.5 documentation" href="../../index.html" />
<link rel="up" title="Deploying Django" href="index.html" />
<link rel="next" title="Error reporting" href="../error-reporting.html" />
<link rel="prev" title="How to use Django with FastCGI, SCGI, or AJP" href="fastcgi.html" />
<script type="text/javascript" src="../../templatebuiltins.js"></script>
<script type="text/javascript">
(function($) {
if (!django_template_builtins) {
// templatebuiltins.js missing, do nothing.
return;
}
$(document).ready(function() {
// Hyperlink Django template tags and filters
var base = "../../ref/templates/builtins.html";
if (base == "#") {
// Special case for builtins.html itself
base = "";
}
// Tags are keywords, class '.k'
$("div.highlight\\-html\\+django span.k").each(function(i, elem) {
var tagname = $(elem).text();
if ($.inArray(tagname, django_template_builtins.ttags) != -1) {
var fragment = tagname.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + tagname + "</a>");
}
});
// Filters are functions, class '.nf'
$("div.highlight\\-html\\+django span.nf").each(function(i, elem) {
var filtername = $(elem).text();
if ($.inArray(filtername, django_template_builtins.tfilters) != -1) {
var fragment = filtername.replace(/_/, '-');
$(elem).html("<a href='" + base + "#" + fragment + "'>" + filtername + "</a>");
}
});
});
})(jQuery);
</script>
</head>
<body>
<div class="document">
<div id="custom-doc" class="yui-t6">
<div id="hd">
<h1><a href="../../index.html">Django 1.4.5 documentation</a></h1>
<div id="global-nav">
<a title="Home page" href="../../index.html">Home</a> |
<a title="Table of contents" href="../../contents.html">Table of contents</a> |
<a title="Global index" href="../../genindex.html">Index</a> |
<a title="Module index" href="../../py-modindex.html">Modules</a>
</div>
<div class="nav">
« <a href="fastcgi.html" title="How to use Django with FastCGI, SCGI, or AJP">previous</a>
|
<a href="../index.html" title="&#8220;How-to&#8221; guides" accesskey="U">up</a>
|
<a href="../error-reporting.html" title="Error reporting">next</a> »</div>
</div>
<div id="bd">
<div id="yui-main">
<div class="yui-b">
<div class="yui-g" id="howto-deployment-modpython">
<div class="section" id="s-how-to-use-django-with-apache-and-mod-python">
<span id="how-to-use-django-with-apache-and-mod-python"></span><h1>How to use Django with Apache and mod_python<a class="headerlink" href="#how-to-use-django-with-apache-and-mod-python" title="Permalink to this headline">¶</a></h1>
<div class="admonition warning">
<p class="first admonition-title">Warning</p>
<p class="last">Support for mod_python has been deprecated, and will be removed in
Django 1.5. If you are configuring a new deployment, you are
strongly encouraged to consider using <a class="reference internal" href="wsgi/modwsgi.html"><em>mod_wsgi</em></a> or any of the other <a class="reference internal" href="index.html"><em>supported
servers</em></a>.</p>
</div>
<p>The <a class="reference external" href="http://www.modpython.org/">mod_python</a> module for <a class="reference external" href="http://httpd.apache.org/">Apache</a> can be used to deploy Django to a
production server, although it has been mostly superseded by the simpler
<a class="reference internal" href="wsgi/modwsgi.html"><em>mod_wsgi deployment option</em></a>.</p>
<p>mod_python is similar to (and inspired by) <a class="reference external" href="http://perl.apache.org/">mod_perl</a> : It embeds Python within
Apache and loads Python code into memory when the server starts. Code stays in
memory throughout the life of an Apache process, which leads to significant
performance gains over other server arrangements.</p>
<p>Django requires Apache 2.x and mod_python 3.x, and you should use Apache’s
<a class="reference external" href="http://httpd.apache.org/docs/2.2/mod/prefork.html">prefork MPM</a>, as opposed to the <a class="reference external" href="http://httpd.apache.org/docs/2.2/mod/worker.html">worker MPM</a>.</p>
<div class="admonition-see-also admonition seealso">
<p class="first admonition-title">See also</p>
<ul class="last simple">
<li>Apache is a big, complex animal, and this document only scratches the
surface of what Apache can do. If you need more advanced information about
Apache, there’s no better source than <a class="reference external" href="http://httpd.apache.org/docs/">Apache’s own official
documentation</a></li>
<li>You may also be interested in <a class="reference internal" href="fastcgi.html"><em>How to use Django with FastCGI, SCGI,
or AJP</em></a>.</li>
</ul>
</div>
<div class="section" id="s-basic-configuration">
<span id="basic-configuration"></span><h2>Basic configuration<a class="headerlink" href="#basic-configuration" title="Permalink to this headline">¶</a></h2>
<p>To configure Django with mod_python, first make sure you have Apache installed,
with the mod_python module activated.</p>
<p>Then edit your <tt class="docutils literal"><span class="pre">httpd.conf</span></tt> file and add the following:</p>
<div class="highlight-apache"><div class="highlight"><pre><span class="nt"><Location</span> <span class="s">"/mysite/"</span><span class="nt">></span>
<span class="nb">SetHandler</span> python-program
<span class="nb">PythonHandler</span> django.core.handlers.modpython
<span class="nb">SetEnv</span> DJANGO_SETTINGS_MODULE mysite.settings
<span class="nb">PythonOption</span> django.root <span class="sx">/mysite</span>
<span class="nb">PythonDebug</span> <span class="k">On</span>
<span class="nt"></Location></span>
</pre></div>
</div>
<p>...and replace <tt class="docutils literal"><span class="pre">mysite.settings</span></tt> with the Python import path to your Django
project’s settings file.</p>
<p>This tells Apache: “Use mod_python for any URL at or under ‘/mysite/’, using the
Django mod_python handler.” It passes the value of <a class="reference internal" href="../../topics/settings.html#django-settings-module"><em>DJANGO_SETTINGS_MODULE</em></a> so mod_python knows which settings to use.</p>
<p>Because mod_python does not know we are serving this site from underneath the
<tt class="docutils literal"><span class="pre">/mysite/</span></tt> prefix, this value needs to be passed through to the mod_python
handler in Django, via the <tt class="docutils literal"><span class="pre">PythonOption</span> <span class="pre">django.root</span> <span class="pre">...</span></tt> line. The value set
on that line (the last item) should match the string given in the <tt class="docutils literal"><span class="pre"><Location</span>
<span class="pre">...></span></tt> directive. The effect of this is that Django will automatically strip the
<tt class="docutils literal"><span class="pre">/mysite</span></tt> string from the front of any URLs before matching them against your
URLconf patterns. If you later move your site to live under <tt class="docutils literal"><span class="pre">/mysite2</span></tt>, you
will not have to change anything except the <tt class="docutils literal"><span class="pre">django.root</span></tt> option in the config
file.</p>
<p>When using <tt class="docutils literal"><span class="pre">django.root</span></tt> you should make sure that what’s left, after the
prefix has been removed, begins with a slash. Your URLconf patterns that are
expecting an initial slash will then work correctly. In the above example,
since we want to send things like <tt class="docutils literal"><span class="pre">/mysite/admin/</span></tt> to <tt class="docutils literal"><span class="pre">/admin/</span></tt>, we need
to remove the string <tt class="docutils literal"><span class="pre">/mysite</span></tt> from the beginning, so that is the
<tt class="docutils literal"><span class="pre">django.root</span></tt> value. It would be an error to use <tt class="docutils literal"><span class="pre">/mysite/</span></tt> (with a
trailing slash) in this case.</p>
<p>Note that we’re using the <tt class="docutils literal"><span class="pre"><Location></span></tt> directive, not the <tt class="docutils literal"><span class="pre"><Directory></span></tt>
directive. The latter is used for pointing at places on your filesystem,
whereas <tt class="docutils literal"><span class="pre"><Location></span></tt> points at places in the URL structure of a Web site.
<tt class="docutils literal"><span class="pre"><Directory></span></tt> would be meaningless here.</p>
<p>Also, if your Django project is not on the default <tt class="docutils literal"><span class="pre">PYTHONPATH</span></tt> for your
computer, you’ll have to tell mod_python where your project can be found:</p>
<pre class="literal-block">
<Location "/mysite/">
SetHandler python-program
PythonHandler django.core.handlers.modpython
SetEnv DJANGO_SETTINGS_MODULE mysite.settings
PythonOption django.root /mysite
PythonDebug On
<strong>PythonPath "['/path/to/project'] + sys.path"</strong>
</Location>
</pre>
<p>The value you use for <tt class="docutils literal"><span class="pre">PythonPath</span></tt> should include the parent directories of
all the modules you are going to import in your application. It should also
include the parent directory of the <a class="reference internal" href="../../topics/settings.html#django-settings-module"><em>DJANGO_SETTINGS_MODULE</em></a> location. This is exactly the same situation as
setting the Python path for interactive usage. Whenever you try to import
something, Python will run through all the directories in <tt class="docutils literal"><span class="pre">sys.path</span></tt> in turn,
from first to last, and try to import from each directory until one succeeds.</p>
<p>Make sure that your Python source files’ permissions are set such that the
Apache user (usually named <tt class="docutils literal"><span class="pre">apache</span></tt> or <tt class="docutils literal"><span class="pre">httpd</span></tt> on most systems) will have
read access to the files.</p>
<p>An example might make this clearer. Suppose you have some applications under
<tt class="docutils literal"><span class="pre">/usr/local/django-apps/</span></tt> (for example, <tt class="docutils literal"><span class="pre">/usr/local/django-apps/weblog/</span></tt> and
so forth), your settings file is at <tt class="docutils literal"><span class="pre">/var/www/mysite/settings.py</span></tt> and you have
specified <a class="reference internal" href="../../topics/settings.html#django-settings-module"><em>DJANGO_SETTINGS_MODULE</em></a> as in the above
example. In this case, you would need to write your <tt class="docutils literal"><span class="pre">PythonPath</span></tt> directive
as:</p>
<div class="highlight-apache"><div class="highlight"><pre><span class="nb">PythonPath</span> <span class="s2">"['/usr/local/django-apps/', '/var/www'] + sys.path"</span>
</pre></div>
</div>
<p>With this path, <tt class="docutils literal"><span class="pre">import</span> <span class="pre">weblog</span></tt> and <tt class="docutils literal"><span class="pre">import</span> <span class="pre">mysite.settings</span></tt> will both
work. If you had <tt class="docutils literal"><span class="pre">import</span> <span class="pre">blogroll</span></tt> in your code somewhere and <tt class="docutils literal"><span class="pre">blogroll</span></tt>
lived under the <tt class="docutils literal"><span class="pre">weblog/</span></tt> directory, you would <em>also</em> need to add
<tt class="docutils literal"><span class="pre">/usr/local/django-apps/weblog/</span></tt> to your <tt class="docutils literal"><span class="pre">PythonPath</span></tt>. Remember: the
<strong>parent directories</strong> of anything you import directly must be on the Python
path.</p>
<div class="admonition note">
<p class="first admonition-title">Note</p>
<p>If you’re using Windows, we still recommended that you use forward
slashes in the pathnames, even though Windows normally uses the backslash
character as its native separator. Apache knows how to convert from the
forward slash format to the native format, so this approach is portable and
easier to read. (It avoids tricky problems with having to double-escape
backslashes.)</p>
<p>This is valid even on a Windows system:</p>
<div class="last highlight-apache"><div class="highlight"><pre><span class="nb">PythonPath</span> <span class="s2">"['c:/path/to/project'] + sys.path"</span>
</pre></div>
</div>
</div>
<p>You can also add directives such as <tt class="docutils literal"><span class="pre">PythonAutoReload</span> <span class="pre">Off</span></tt> for performance.
See the <a class="reference external" href="http://modpython.org/live/current/doc-html/directives.html">mod_python documentation</a> for a full list of options.</p>
<p>Note that you should set <tt class="docutils literal"><span class="pre">PythonDebug</span> <span class="pre">Off</span></tt> on a production server. If you
leave <tt class="docutils literal"><span class="pre">PythonDebug</span> <span class="pre">On</span></tt>, your users would see ugly (and revealing) Python
tracebacks if something goes wrong within mod_python.</p>
<p>Restart Apache, and any request to <tt class="docutils literal"><span class="pre">/mysite/</span></tt> or below will be served by
Django. Note that Django’s URLconfs won’t trim the “/mysite/” – they get passed
the full URL.</p>
<p>When deploying Django sites on mod_python, you’ll need to restart Apache each
time you make changes to your Python code.</p>
</div>
<div class="section" id="s-multiple-django-installations-on-the-same-apache">
<span id="multiple-django-installations-on-the-same-apache"></span><h2>Multiple Django installations on the same Apache<a class="headerlink" href="#multiple-django-installations-on-the-same-apache" title="Permalink to this headline">¶</a></h2>
<p>It’s entirely possible to run multiple Django installations on the same Apache
instance. Just use <tt class="docutils literal"><span class="pre">VirtualHost</span></tt> for that, like so:</p>
<div class="highlight-apache"><div class="highlight"><pre><span class="nb">NameVirtualHost</span> *
<span class="nt"><VirtualHost</span> <span class="s">*</span><span class="nt">></span>
<span class="nb">ServerName</span> www.example.com
<span class="c"># ...</span>
<span class="nb">SetEnv</span> DJANGO_SETTINGS_MODULE mysite.settings
<span class="nt"></VirtualHost></span>
<span class="nt"><VirtualHost</span> <span class="s">*</span><span class="nt">></span>
<span class="nb">ServerName</span> www2.example.com
<span class="c"># ...</span>
<span class="nb">SetEnv</span> DJANGO_SETTINGS_MODULE mysite.other_settings
<span class="nt"></VirtualHost></span>
</pre></div>
</div>
<p>If you need to put two Django installations within the same <tt class="docutils literal"><span class="pre">VirtualHost</span></tt>
(or in different <tt class="docutils literal"><span class="pre">VirtualHost</span></tt> blocks that share the same server name),
you’ll need to take a special precaution to ensure mod_python’s cache doesn’t
mess things up. Use the <tt class="docutils literal"><span class="pre">PythonInterpreter</span></tt> directive to give different
<tt class="docutils literal"><span class="pre"><Location></span></tt> directives separate interpreters:</p>
<div class="highlight-apache"><div class="highlight"><pre><span class="nt"><VirtualHost</span> <span class="s">*</span><span class="nt">></span>
<span class="nb">ServerName</span> www.example.com
<span class="c"># ...</span>
<span class="nt"><Location</span> <span class="s">"/something"</span><span class="nt">></span>
<span class="nb">SetEnv</span> DJANGO_SETTINGS_MODULE mysite.settings
<span class="nb">PythonInterpreter</span> mysite
<span class="nt"></Location></span>
<span class="nt"><Location</span> <span class="s">"/otherthing"</span><span class="nt">></span>
<span class="nb">SetEnv</span> DJANGO_SETTINGS_MODULE mysite.other_settings
<span class="nb">PythonInterpreter</span> othersite
<span class="nt"></Location></span>
<span class="nt"></VirtualHost></span>
</pre></div>
</div>
<p>The values of <tt class="docutils literal"><span class="pre">PythonInterpreter</span></tt> don’t really matter, as long as they’re
different between the two <tt class="docutils literal"><span class="pre">Location</span></tt> blocks.</p>
</div>
<div class="section" id="s-running-a-development-server-with-mod-python">
<span id="running-a-development-server-with-mod-python"></span><h2>Running a development server with mod_python<a class="headerlink" href="#running-a-development-server-with-mod-python" title="Permalink to this headline">¶</a></h2>
<p>If you use mod_python for your development server, you can avoid the hassle of
having to restart the server each time you make code changes. Just set
<tt class="docutils literal"><span class="pre">MaxRequestsPerChild</span> <span class="pre">1</span></tt> in your <tt class="docutils literal"><span class="pre">httpd.conf</span></tt> file to force Apache to reload
everything for each request. But don’t do that on a production server, or we’ll
revoke your Django privileges.</p>
<p>If you’re the type of programmer who debugs using scattered <tt class="docutils literal"><span class="pre">print</span></tt>
statements, note that output to <tt class="docutils literal"><span class="pre">stdout</span></tt> will not appear in the Apache
log and can even <a class="reference external" href="http://blog.dscpl.com.au/2009/04/wsgi-and-printing-to-standard-output.html">cause response errors</a>.</p>
<p>If you have the need to print debugging information in a mod_python setup, you
have a few options. You can print to <tt class="docutils literal"><span class="pre">stderr</span></tt> explicitly, like so:</p>
<div class="highlight-apache"><pre>print >> sys.stderr, 'debug text'
sys.stderr.flush()</pre>
</div>
<p>(note that <tt class="docutils literal"><span class="pre">stderr</span></tt> is buffered, so calling <tt class="docutils literal"><span class="pre">flush</span></tt> is necessary if you wish
debugging information to be displayed promptly.)</p>
<p>A more compact approach is to use an assertion:</p>
<div class="highlight-apache"><div class="highlight"><pre><span class="nb">assert</span> False, 'debug text'
</pre></div>
</div>
<p>Another alternative is to add debugging information to the template of your page.</p>
</div>
<div class="section" id="s-serving-media-files">
<span id="serving-media-files"></span><h2>Serving media files<a class="headerlink" href="#serving-media-files" title="Permalink to this headline">¶</a></h2>
<p>Django doesn’t serve media files itself; it leaves that job to whichever Web
server you choose.</p>
<p>We recommend using a separate Web server – i.e., one that’s not also running
Django – for serving media. Here are some good choices:</p>
<ul class="simple">
<li><a class="reference external" href="http://www.lighttpd.net/">lighttpd</a></li>
<li><a class="reference external" href="http://wiki.nginx.org/Main">Nginx</a></li>
<li><a class="reference external" href="http://en.wikipedia.org/wiki/TUX_web_server">TUX</a></li>
<li>A stripped-down version of <a class="reference external" href="http://httpd.apache.org/">Apache</a></li>
<li><a class="reference external" href="http://www.cherokee-project.com/">Cherokee</a></li>
</ul>
<p>If, however, you have no option but to serve media or static files on the
same Apache <tt class="docutils literal"><span class="pre">VirtualHost</span></tt> as Django, here’s how you can turn off mod_python
for a particular part of the site:</p>
<div class="highlight-apache"><div class="highlight"><pre><span class="nt"><Location</span> <span class="s">"/media"</span><span class="nt">></span>
<span class="nb">SetHandler</span> <span class="k">None</span>
<span class="nt"></Location></span>
</pre></div>
</div>
<p>Just change <tt class="docutils literal"><span class="pre">Location</span></tt> to the root URL of your media files. You can also use
<tt class="docutils literal"><span class="pre"><LocationMatch></span></tt> to match a regular expression.</p>
<p>This example sets up Django at the site root but explicitly disables Django
for the <tt class="docutils literal"><span class="pre">media</span></tt> and <tt class="docutils literal"><span class="pre">static</span></tt> subdirectories and any URL that ends with
<tt class="docutils literal"><span class="pre">.jpg</span></tt>, <tt class="docutils literal"><span class="pre">.gif</span></tt> or <tt class="docutils literal"><span class="pre">.png</span></tt>:</p>
<div class="highlight-apache"><div class="highlight"><pre><span class="nt"><Location</span> <span class="s">"/"</span><span class="nt">></span>
<span class="nb">SetHandler</span> python-program
<span class="nb">PythonHandler</span> django.core.handlers.modpython
<span class="nb">SetEnv</span> DJANGO_SETTINGS_MODULE mysite.settings
<span class="nt"></Location></span>
<span class="nt"><Location</span> <span class="s">"/media"</span><span class="nt">></span>
<span class="nb">SetHandler</span> <span class="k">None</span>
<span class="nt"></Location></span>
<span class="nt"><Location</span> <span class="s">"/static"</span><span class="nt">></span>
<span class="nb">SetHandler</span> <span class="k">None</span>
<span class="nt"></Location></span>
<span class="nt"><LocationMatch</span> <span class="s">"\.(jpg|gif|png)$"</span><span class="nt">></span>
<span class="nb">SetHandler</span> <span class="k">None</span>
<span class="nt"></LocationMatch></span>
</pre></div>
</div>
</div>
<div class="section" id="s-serving-the-admin-files">
<span id="serving-the-admin-files"></span><h2>Serving the admin files<a class="headerlink" href="#serving-the-admin-files" title="Permalink to this headline">¶</a></h2>
<p>Note that the Django development server automagically serves the static files
of the admin app, but this is not the case when you use any other server
arrangement. You’re responsible for setting up Apache, or whichever media
server you’re using, to serve the admin files.</p>
<p>The admin files live in (<tt class="file docutils literal"><span class="pre">django/contrib/admin/static/admin</span></tt>) of the
Django distribution.</p>
<p>We <strong>strongly</strong> recommend using <a class="reference internal" href="../../ref/contrib/staticfiles.html#module-django.contrib.staticfiles" title="django.contrib.staticfiles: An app for handling static files."><tt class="xref py py-mod docutils literal"><span class="pre">django.contrib.staticfiles</span></tt></a> to handle the
admin files (this means using the <a class="reference internal" href="../../ref/contrib/staticfiles.html#django-admin-collectstatic"><tt class="xref std std-djadmin docutils literal"><span class="pre">collectstatic</span></tt></a> management command
to collect the static files in <a class="reference internal" href="../../ref/settings.html#std:setting-STATIC_ROOT"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_ROOT</span></tt></a>, and then configuring
your Web server to serve <a class="reference internal" href="../../ref/settings.html#std:setting-STATIC_ROOT"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_ROOT</span></tt></a> at <a class="reference internal" href="../../ref/settings.html#std:setting-STATIC_URL"><tt class="xref std std-setting docutils literal"><span class="pre">STATIC_URL</span></tt></a>), but
here are two other approaches:</p>
<ol class="arabic simple">
<li>Create a symbolic link to the admin static files from within your
document root.</li>
<li>Or, copy the admin static files so that they live within your Apache
document root.</li>
</ol>
</div>
<div class="section" id="s-using-eggs-with-mod-python">
<span id="using-eggs-with-mod-python"></span><h2>Using “eggs” with mod_python<a class="headerlink" href="#using-eggs-with-mod-python" title="Permalink to this headline">¶</a></h2>
<p>If you installed Django from a Python <a class="reference external" href="http://peak.telecommunity.com/DevCenter/PythonEggs">egg</a> or are using eggs in your Django
project, some extra configuration is required. Create an extra file in your
project (or somewhere else) that contains something like the following:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">import</span> <span class="nn">os</span>
<span class="n">os</span><span class="o">.</span><span class="n">environ</span><span class="p">[</span><span class="s">'PYTHON_EGG_CACHE'</span><span class="p">]</span> <span class="o">=</span> <span class="s">'/some/directory'</span>
</pre></div>
</div>
<p>Here, <tt class="docutils literal"><span class="pre">/some/directory</span></tt> is a directory that the Apache Web server process can
write to. It will be used as the location for any unpacking of code the eggs
need to do.</p>
<p>Then you have to tell mod_python to import this file before doing anything
else. This is done using the <a class="reference external" href="http://www.modpython.org/live/current/doc-html/dir-other-pimp.html">PythonImport</a> directive to mod_python. You need
to ensure that you have specified the <tt class="docutils literal"><span class="pre">PythonInterpreter</span></tt> directive to
mod_python as described <a class="reference internal" href="#multiple-django-installations-on-the-same-apache">above</a> (you need to do this even if you aren’t
serving multiple installations in this case). Then add the <tt class="docutils literal"><span class="pre">PythonImport</span></tt>
line in the main server configuration (i.e., outside the <tt class="docutils literal"><span class="pre">Location</span></tt> or
<tt class="docutils literal"><span class="pre">VirtualHost</span></tt> sections). For example:</p>
<div class="highlight-apache"><div class="highlight"><pre><span class="nb">PythonInterpreter</span> my_django
<span class="nb">PythonImport</span> <span class="sx">/path/to/my/project/file.py</span> my_django
</pre></div>
</div>
<p>Note that you can use an absolute path here (or a normal dotted import path),
as described in the <a class="reference external" href="http://www.modpython.org/live/current/doc-html/dir-other-pimp.html">mod_python manual</a>. We use an absolute path in the
above example because if any Python path modifications are required to access
your project, they will not have been done at the time the <tt class="docutils literal"><span class="pre">PythonImport</span></tt>
line is processed.</p>
</div>
<div class="section" id="s-error-handling">
<span id="error-handling"></span><h2>Error handling<a class="headerlink" href="#error-handling" title="Permalink to this headline">¶</a></h2>
<p>When you use Apache/mod_python, errors will be caught by Django – in other
words, they won’t propagate to the Apache level and won’t appear in the Apache
<tt class="docutils literal"><span class="pre">error_log</span></tt>.</p>
<p>The exception for this is if something is really wonky in your Django setup. In
that case, you’ll see an “Internal Server Error” page in your browser and the
full Python traceback in your Apache <tt class="docutils literal"><span class="pre">error_log</span></tt> file. The <tt class="docutils literal"><span class="pre">error_log</span></tt>
traceback is spread over multiple lines. (Yes, this is ugly and rather hard to
read, but it’s how mod_python does things.)</p>
</div>
<div class="section" id="s-if-you-get-a-segmentation-fault">
<span id="if-you-get-a-segmentation-fault"></span><h2>If you get a segmentation fault<a class="headerlink" href="#if-you-get-a-segmentation-fault" title="Permalink to this headline">¶</a></h2>
<p>If Apache causes a segmentation fault, there are two probable causes, neither
of which has to do with Django itself.</p>
<ol class="arabic simple">
<li>It may be because your Python code is importing the “pyexpat” module,
which may conflict with the version embedded in Apache. For full
information, see <a class="reference external" href="http://www.dscpl.com.au/wiki/ModPython/Articles/ExpatCausingApacheCrash">Expat Causing Apache Crash</a>.</li>
<li>It may be because you’re running mod_python and mod_php in the same
Apache instance, with MySQL as your database backend. In some cases,
this causes a known mod_python issue due to version conflicts in PHP and
the Python MySQL backend. There’s full information in the
<a class="reference external" href="http://modpython.org/FAQ/faqw.py?req=show&file=faq02.013.htp">mod_python FAQ entry</a>.</li>
</ol>
<p>If you continue to have problems setting up mod_python, a good thing to do is
get a barebones mod_python site working, without the Django framework. This is
an easy way to isolate mod_python-specific problems. <a class="reference external" href="http://www.dscpl.com.au/wiki/ModPython/Articles/GettingModPythonWorking">Getting mod_python Working</a>
details this procedure.</p>
<p>The next step should be to edit your test code and add an import of any
Django-specific code you’re using – your views, your models, your URLconf,
your RSS configuration, etc. Put these imports in your test handler function
and access your test URL in a browser. If this causes a crash, you’ve confirmed
it’s the importing of Django code that causes the problem. Gradually reduce the
set of imports until it stops crashing, so as to find the specific module that
causes the problem. Drop down further into modules and look into their imports,
as necessary.</p>
</div>
<div class="section" id="s-if-you-get-a-unicodeencodeerror">
<span id="if-you-get-a-unicodeencodeerror"></span><h2>If you get a UnicodeEncodeError<a class="headerlink" href="#if-you-get-a-unicodeencodeerror" title="Permalink to this headline">¶</a></h2>
<p>If you’re taking advantage of the internationalization features of Django (see
<a class="reference internal" href="../../topics/i18n/index.html"><em>Internationalization and localization</em></a>) and you intend to allow users to upload files, you must
ensure that the environment used to start Apache is configured to accept
non-ASCII file names. If your environment is not correctly configured, you
will trigger <tt class="docutils literal"><span class="pre">UnicodeEncodeError</span></tt> exceptions when calling functions like
<tt class="docutils literal"><span class="pre">os.path()</span></tt> on filenames that contain non-ASCII characters.</p>
<p>To avoid these problems, the environment used to start Apache should contain
settings analogous to the following:</p>
<div class="highlight-apache"><div class="highlight"><pre><span class="nb">export</span> LANG='en_US.UTF-8'
<span class="nb">export</span> LC_ALL='en_US.UTF-8'
</pre></div>
</div>
<p>Consult the documentation for your operating system for the appropriate syntax
and location to put these configuration items; <tt class="docutils literal"><span class="pre">/etc/apache2/envvars</span></tt> is a
common location on Unix platforms. Once you have added these statements
to your environment, restart Apache.</p>
</div>
</div>
</div>
</div>
</div>
<div class="yui-b" id="sidebar">
<div class="sphinxsidebar">
<div class="sphinxsidebarwrapper">
<h3><a href="../../contents.html">Table Of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">How to use Django with Apache and mod_python</a><ul>
<li><a class="reference internal" href="#basic-configuration">Basic configuration</a></li>
<li><a class="reference internal" href="#multiple-django-installations-on-the-same-apache">Multiple Django installations on the same Apache</a></li>
<li><a class="reference internal" href="#running-a-development-server-with-mod-python">Running a development server with mod_python</a></li>
<li><a class="reference internal" href="#serving-media-files">Serving media files</a></li>
<li><a class="reference internal" href="#serving-the-admin-files">Serving the admin files</a></li>
<li><a class="reference internal" href="#using-eggs-with-mod-python">Using “eggs” with mod_python</a></li>
<li><a class="reference internal" href="#error-handling">Error handling</a></li>
<li><a class="reference internal" href="#if-you-get-a-segmentation-fault">If you get a segmentation fault</a></li>
<li><a class="reference internal" href="#if-you-get-a-unicodeencodeerror">If you get a UnicodeEncodeError</a></li>
</ul>
</li>
</ul>
<h3>Browse</h3>
<ul>
<li>Prev: <a href="fastcgi.html">How to use Django with FastCGI, SCGI, or AJP</a></li>
<li>Next: <a href="../error-reporting.html">Error reporting</a></li>
</ul>
<h3>You are here:</h3>
<ul>
<li>
<a href="../../index.html">Django 1.4.5 documentation</a>
<ul><li><a href="../index.html">“How-to” guides</a>
<ul><li><a href="index.html">Deploying Django</a>
<ul><li>How to use Django with Apache and mod_python</li></ul>
</li></ul></li></ul>
</li>
</ul>
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="../../_sources/howto/deployment/modpython.txt"
rel="nofollow">Show Source</a></li>
</ul>
<div id="searchbox" style="display: none">
<h3>Quick search</h3>
<form class="search" action="../../search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
<p class="searchtip" style="font-size: 90%">
Enter search terms or a module, class or function name.
</p>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<h3>Last update:</h3>
<p class="topless">Feb 21, 2013</p>
</div>
</div>
<div id="ft">
<div class="nav">
« <a href="fastcgi.html" title="How to use Django with FastCGI, SCGI, or AJP">previous</a>
|
<a href="../index.html" title="&#8220;How-to&#8221; guides" accesskey="U">up</a>
|
<a href="../error-reporting.html" title="Error reporting">next</a> »</div>
</div>
</div>
<div class="clearer"></div>
</div>
</body>
</html>
