diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/faq.txt | 14 | ||||
| -rw-r--r-- | docs/fastcgi.txt | 146 | ||||
| -rw-r--r-- | docs/modpython.txt | 6 | ||||
| -rw-r--r-- | docs/syndication_feeds.txt | 14 | ||||
| -rw-r--r-- | docs/templates_python.txt | 4 |
5 files changed, 122 insertions, 62 deletions
diff --git a/docs/faq.txt b/docs/faq.txt index adcdbaca59..37e15878f2 100644 --- a/docs/faq.txt +++ b/docs/faq.txt @@ -301,16 +301,18 @@ PostgreSQL fans, and MySQL_ and `SQLite 3`_ are also supported. Do I have to use mod_python? ---------------------------- -Not if you just want to play around and develop things on your local computer. -Django comes with its own Web server, and things should Just Work. +Although we recommend mod_python for production use, you don't have to use it, +thanks to the fact that Django uses an arrangement called WSGI_. Django can +talk to any WSGI-enabled server. The most common non-mod_python deployment +setup is FastCGI. See `How to use Django with FastCGI`_ for full information. -For production use, though, we recommend mod_python. The Django developers have -been running it on mod_python for several years, and it's quite stable. +Also, see the `server arrangements wiki page`_ for other deployment strategies. -However, if you don't want to use mod_python, you can use a different server, -as long as that server has WSGI_ hooks. See the `server arrangements wiki page`_. +If you just want to play around and develop things on your local computer, use +the development Web server that comes with Django. Things should Just Work. .. _WSGI: http://www.python.org/peps/pep-0333.html +.. _How to use Django with FastCGI: http://www.djangoproject.com/documentation/fastcgi/ .. _server arrangements wiki page: http://code.djangoproject.com/wiki/ServerArrangements How do I install mod_python on Windows? diff --git a/docs/fastcgi.txt b/docs/fastcgi.txt index 41b9561b6d..41d50d97a1 100644 --- a/docs/fastcgi.txt +++ b/docs/fastcgi.txt @@ -2,7 +2,7 @@ How to use Django with FastCGI ============================== -Although the current preferred setup for running Django is Apache_ with +Although the `current preferred setup`_ for running Django is Apache_ with `mod_python`_, many people use shared hosting, on which FastCGI is the only viable option. In some setups, FastCGI also allows better security -- and, possibly, better performance -- than mod_python. @@ -17,6 +17,7 @@ served with no startup time. Unlike mod_python (or `mod_perl`_), a FastCGI process doesn't run inside the Web server process, but in a separate, persistent process. +.. _current preferred setup: http://www.djangoproject.com/documentation/modpython/ .. _Apache: http://httpd.apache.org/ .. _mod_python: http://www.modpython.org/ .. _mod_perl: http://perl.apache.org/ @@ -35,6 +36,16 @@ persistent process. security benefit on shared systems, because it means you can secure your code from other users. +Prerequisite: flup +================== + +Before you can start using FastCGI with Django, you'll need to install flup_, +which is a Python library for dealing with FastCGI. Make sure to use the latest +Subversion snapshot of flup, as some users have reported stalled pages with +older flup versions. + +.. _flup: http://www.saddi.com/software/flup/ + Starting your FastCGI server ============================ @@ -120,18 +131,53 @@ Apache setup ============ To use Django with Apache and FastCGI, you'll need Apache installed and -configured, with mod_fastcgi installed and enabled. Consult the Apache +configured, with `mod_fastcgi`_ installed and enabled. Consult the Apache documentation for instructions. -Add the following to your ``httpd.conf``:: +Once you've got that set up, point Apache at your Django FastCGI instance by +editing the ``httpd.conf`` (Apache configuration) file. You'll need to do two +things: + + * Use the ``FastCGIExternalServer`` directive to specify the location of + your FastCGI server. + * Use ``mod_rewrite`` to point URLs at FastCGI as appropriate. + +.. _mod_fastcgi: http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html + +Specifying the location of the FastCGI server +--------------------------------------------- + +The ``FastCGIExternalServer`` directive tells Apache how to find your FastCGI +server. As the `FastCGIExternalServer docs`_ explain, you can specify either a +``socket`` or a ``host``. Here are examples of both:: - # Connect to FastCGI via a socket / named pipe + # Connect to FastCGI via a socket / named pipe. FastCGIExternalServer /home/user/public_html/mysite.fcgi -socket /home/user/mysite.sock - # Connect to FastCGI via a TCP host/port - # FastCGIExternalServer /home/user/public_html/mysite.fcgi -host 127.0.0.1:3033 - <VirtualHost 64.92.160.91> - ServerName mysite.com + # Connect to FastCGI via a TCP host/port. + FastCGIExternalServer /home/user/public_html/mysite.fcgi -host 127.0.0.1:3033 + +In either case, the file ``/home/user/public_html/mysite.fcgi`` doesn't +actually have to exist. It's just a URL used by the Web server internally -- a +hook for signifying which requests at a URL should be handled by FastCGI. (More +on this in the next section.) + +.. _FastCGIExternalServer docs: http://www.fastcgi.com/mod_fastcgi/docs/mod_fastcgi.html#FastCgiExternalServer + +Using mod_rewrite to point URLs at FastCGI +------------------------------------------ + +The second step is telling Apache to use FastCGI for URLs that match a certain +pattern. To do this, use the `mod_rewrite`_ module and rewrite URLs to +``mysite.fcgi`` (or whatever you specified in the ``FastCGIExternalServer`` +directive, as explained in the previous section). + +In this example, we tell Apache to use FastCGI to handle any request that +doesn't represent a file on the filesystem and doesn't start with ``/media/``. +This is probably the most common case, if you're using Django's admin site:: + + <VirtualHost 12.34.56.78> + ServerName example.com DocumentRoot /home/user/public_html Alias /media /home/user/python/django/contrib/admin/media RewriteEngine On @@ -140,22 +186,18 @@ Add the following to your ``httpd.conf``:: RewriteRule ^/(.*)$ /mysite.fcgi/$1 [QSA,L] </VirtualHost> -Note that while you have to specify a mysite.fcgi, that this file doesn't -actually have to exist. It is just an internal URL to the webserver which -signifies that any requests to that URL will go to the external FastCGI -server. +.. _mod_rewrite: http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html -LigHTTPd Setup +lighttpd setup ============== -LigHTTPd is a light-weight asynchronous web-server, which is commonly used -for serving static files. However, it supports FastCGI natively, and as such -is a very good choice for serving both static and dynamic media, if your site -does not have any apache-specific components. +lighttpd is a lightweight Web server commonly used for serving static files. It +supports FastCGI natively and, thus, is a good choice for serving both static +and dynamic pages, if your site doesn't have any Apache-specific needs. Make sure ``mod_fastcgi`` is in your modules list, somewhere after -mod_rewrite and mod_access, but not after mod_accesslog. You'll probably -want mod_alias as well, for serving admin media. +``mod_rewrite`` and ``mod_access``, but not after ``mod_accesslog``. You'll +probably want ``mod_alias`` as well, for serving admin media. Add the following to your lighttpd config file:: @@ -165,7 +207,7 @@ Add the following to your lighttpd config file:: "main" => ( # Use host / port instead of socket for TCP fastcgi # "host" => "127.0.0.1", - # "port" => 3033, + # "port" => 3033, "socket" => "/home/user/mysite.sock", "check-local" => "disable", ) @@ -181,14 +223,15 @@ Add the following to your lighttpd config file:: "^(/.*)$" => "/mysite.fcgi$1", ) -Running multiple django sites on one LigHTTPd +Running multiple Django sites on one lighttpd --------------------------------------------- -LigHTTPd allows you to use what is called conditional configuration to allow -configuration to be customized per-host. In order to specify multiple fastcgi -sites, simply add a conditional block around your fastcgi config for each site:: +lighttpd lets you use "conditional configuration" to allow configuration to be +customized per host. To specify multiple FastCGI sites, just add a conditional +block around your FastCGI config for each site:: - $HTTP["host"] == "www.website1.com" { + # If the hostname is 'www.example1.com'... + $HTTP["host"] == "www.example1.com" { server.document-root = "/foo/site1" fastcgi.server = ( ... @@ -196,7 +239,8 @@ sites, simply add a conditional block around your fastcgi config for each site:: ... } - $HTTP["host"] == "www.website2.com" { + # If the hostname is 'www.example2.com'... + $HTTP["host"] == "www.example2.com" { server.document-root = "/foo/site2" fastcgi.server = ( ... @@ -204,44 +248,44 @@ sites, simply add a conditional block around your fastcgi config for each site:: ... } -You can also run multiple django installations on the same site simply by -specifying multiple entries in the ``fastcgi.server`` directive, add one -fastcgi host for each. +You can also run multiple Django installations on the same site simply by +specifying multiple entries in the ``fastcgi.server`` directive. Add one +FastCGI host for each. -Running Django on a shared-hosting provider -=========================================== +Running Django on a shared-hosting provider with Apache +======================================================= -For many users on shared-hosting providers, you aren't able to run your own -server daemons nor do they have access to the httpd.conf of their webserver. -However, it is still possible to run Django using webserver-spawned processes. +Many shared-hosting providers don't allow you to run your own server daemons or +edit the ``httpd.conf`` file. In these cases, it's still possible to run Django +using Web server-spawned processes. .. admonition:: Note - If you are using webserver-managed processes, there's no need for you - to start the FastCGI server on your own. Apache will spawn a number - of processes, scaling as it needs to. + If you're using Web server-spawned processes, as explained in this section, + there's no need for you to start the FastCGI server on your own. Apache + will spawn a number of processes, scaling as it needs to. -In your web root directory, add this to a file named .htaccess :: +In your Web root directory, add this to a file named ``.htaccess`` :: AddHandler fastcgi-script .fcgi RewriteEngine On RewriteCond %{REQUEST_FILENAME} !-f RewriteRule ^/(.*)$ /mysite.fcgi/$1 [QSA,L] -Now you must add a small shim script in order for apache to properly -spawn your FastCGI program. Create a mysite.fcgi and place it in your -web directory, making it executable :: +Then, create a small script that tells Apache how to spawn your FastCGI +program. Create a file ``mysite.fcgi`` and place it in your Web directory, and +be sure to make it executable :: #!/usr/bin/python import sys, os - # add a custom pythonpath + # Add a custom Python path. sys.path.insert(0, "/home/user/python") - # switch to the directory of your project. (optional) + # Switch to the directory of your project. (Optional.) # os.chdir("/home/user/myproject") - # change to the name of your app's settings module + # Set the DJANGO_SETTINGS_MODULE environment variable. os.environ['DJANGO_SETTINGS_MODULE'] = "myproject.settings" from django.core.servers.fastcgi import runfastcgi @@ -250,13 +294,13 @@ web directory, making it executable :: Restarting the spawned server ----------------------------- -If you change the code of your site, to make apache re-load your django -application, you do not need to restart the server. Simply re-upload or -edit your ``mysite.fcgi`` in such a way that the timestamp on the file -will change. When apache sees that the file has been updated, it will -restart your django application for you. +If you change any Python code on your site, you'll need to tell FastCGI the +code has changed. But there's no need to restart Apache in this case. Rather, +just reupload ``mysite.fcgi``, or edit the file, so that the timestamp on the +file will change. When Apache sees the file has been updated, it will restart +your Django application for you. -If you have access to a command shell on a unix system, restarting the -server can be done with the ``touch`` command:: +If you have access to a command shell on a Unix system, you can accomplish this +easily by using the ``touch`` command:: touch mysite.fcgi diff --git a/docs/modpython.txt b/docs/modpython.txt index 0c0219e2e9..b88874d3d3 100644 --- a/docs/modpython.txt +++ b/docs/modpython.txt @@ -10,15 +10,17 @@ 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. -Django requires Apache 2.x and mod_python 3.x. +Django requires Apache 2.x and mod_python 3.x, and you should use Apache's +`prefork MPM`_, as opposed to the `worker MPM`_. -We recommend you use Apache's `prefork MPM`_, as opposed to the `worker MPM`_. +You may also be interested in `How to use Django with FastCGI`_. .. _Apache: http://httpd.apache.org/ .. _mod_python: http://www.modpython.org/ .. _mod_perl: http://perl.apache.org/ .. _prefork MPM: http://httpd.apache.org/docs/2.2/mod/prefork.html .. _worker MPM: http://httpd.apache.org/docs/2.2/mod/worker.html +.. _How to use Django with FastCGI: http://www.djangoproject.com/documentation/fastcgi/ Basic configuration =================== diff --git a/docs/syndication_feeds.txt b/docs/syndication_feeds.txt index 4f77c4ff21..c84785b20b 100644 --- a/docs/syndication_feeds.txt +++ b/docs/syndication_feeds.txt @@ -134,7 +134,9 @@ put into those elements. If you don't create a template for either the title or description, the framework will use the template ``"{{ obj }}"`` by default -- that is, - the normal string representation of the object. + the normal string representation of the object. You can also change the + names of these two templates by specifying ``title_template`` and + ``description_template`` as attributes of your ``Feed`` class. * To specify the contents of ``<link>``, you have two options. For each item in ``items()``, Django first tries executing a ``get_absolute_url()`` method on that object. If that method doesn't @@ -342,6 +344,16 @@ This example illustrates all possible attributes and methods for a ``Feed`` clas feed_type = feedgenerator.Rss201rev2Feed + # TEMPLATE NAMES -- Optional. These should be strings representing + # names of Django templates that the system should use in rendering the + # title and description of your feed items. Both are optional. + # If you don't specify one, or either, Django will use the template + # 'feeds/SLUG_title.html' and 'feeds/SLUG_description.html', where SLUG + # is the slug you specify in the URL. + + title_template = None + description_template = None + # TITLE -- One of the following three is required. The framework looks # for them in this order. diff --git a/docs/templates_python.txt b/docs/templates_python.txt index 5e3038ebb4..2fa837e424 100644 --- a/docs/templates_python.txt +++ b/docs/templates_python.txt @@ -783,7 +783,7 @@ Our earlier ``current_time`` function could thus be written like this:: In Python 2.4, the decorator syntax also works:: - @simple_tag + @register.simple_tag def do_current_time(token): ... @@ -844,7 +844,7 @@ loader, we'd register the tag like this:: As always, Python 2.4 decorator syntax works as well, so we could have written:: - @inclusion_tag('results.html') + @register.inclusion_tag('results.html') def show_results(poll): ... |