diff options
| author | Nishanth Amuluru | 2011-01-08 11:20:57 +0530 |
|---|---|---|
| committer | Nishanth Amuluru | 2011-01-08 11:20:57 +0530 |
| commit | 65411d01d448ff0cd4abd14eee14cf60b5f8fc20 (patch) | |
| tree | b4c404363c4c63a61d6e2f8bd26c5b057c1fb09d /parts/django/docs/howto/deployment/fastcgi.txt | |
| parent | 2e35094d43b4cc6974172e1febf76abb50f086ec (diff) | |
| download | pytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.tar.gz pytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.tar.bz2 pytask-65411d01d448ff0cd4abd14eee14cf60b5f8fc20.zip | |
Added buildout stuff and made changes accordingly
--HG--
rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/djangorecipe-0.20-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/infrae.subversion-1.4.5-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/mercurial-1.7.3-py2.6-linux-x86_64.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/py-1.4.0-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/zc.buildout-1.5.2-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/dependency_links.txt
rename : profile/management/__init__.py => eggs/zc.recipe.egg-1.3.2-py2.6.egg/EGG-INFO/not-zip-safe
rename : profile/management/__init__.py => parts/django/Django.egg-info/dependency_links.txt
rename : taskapp/models.py => parts/django/django/conf/app_template/models.py
rename : taskapp/tests.py => parts/django/django/conf/app_template/tests.py
rename : taskapp/views.py => parts/django/django/conf/app_template/views.py
rename : taskapp/views.py => parts/django/django/contrib/gis/tests/geo3d/views.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/delete/__init__.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/files/__init__.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/invalid_models/__init__.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/m2m_signals/__init__.py
rename : profile/management/__init__.py => parts/django/tests/modeltests/model_package/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/management/commands/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/bash_completion/models.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/delete_regress/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/file_storage/__init__.py
rename : profile/management/__init__.py => parts/django/tests/regressiontests/max_lengths/__init__.py
rename : profile/forms.py => pytask/profile/forms.py
rename : profile/management/__init__.py => pytask/profile/management/__init__.py
rename : profile/management/commands/seed_db.py => pytask/profile/management/commands/seed_db.py
rename : profile/models.py => pytask/profile/models.py
rename : profile/templatetags/user_tags.py => pytask/profile/templatetags/user_tags.py
rename : taskapp/tests.py => pytask/profile/tests.py
rename : profile/urls.py => pytask/profile/urls.py
rename : profile/utils.py => pytask/profile/utils.py
rename : profile/views.py => pytask/profile/views.py
rename : static/css/base.css => pytask/static/css/base.css
rename : taskapp/tests.py => pytask/taskapp/tests.py
rename : taskapp/views.py => pytask/taskapp/views.py
rename : templates/base.html => pytask/templates/base.html
rename : templates/profile/browse_notifications.html => pytask/templates/profile/browse_notifications.html
rename : templates/profile/edit.html => pytask/templates/profile/edit.html
rename : templates/profile/view.html => pytask/templates/profile/view.html
rename : templates/profile/view_notification.html => pytask/templates/profile/view_notification.html
rename : templates/registration/activate.html => pytask/templates/registration/activate.html
rename : templates/registration/activation_email.txt => pytask/templates/registration/activation_email.txt
rename : templates/registration/activation_email_subject.txt => pytask/templates/registration/activation_email_subject.txt
rename : templates/registration/logged_out.html => pytask/templates/registration/logged_out.html
rename : templates/registration/login.html => pytask/templates/registration/login.html
rename : templates/registration/logout.html => pytask/templates/registration/logout.html
rename : templates/registration/password_change_done.html => pytask/templates/registration/password_change_done.html
rename : templates/registration/password_change_form.html => pytask/templates/registration/password_change_form.html
rename : templates/registration/password_reset_complete.html => pytask/templates/registration/password_reset_complete.html
rename : templates/registration/password_reset_confirm.html => pytask/templates/registration/password_reset_confirm.html
rename : templates/registration/password_reset_done.html => pytask/templates/registration/password_reset_done.html
rename : templates/registration/password_reset_email.html => pytask/templates/registration/password_reset_email.html
rename : templates/registration/password_reset_form.html => pytask/templates/registration/password_reset_form.html
rename : templates/registration/registration_complete.html => pytask/templates/registration/registration_complete.html
rename : templates/registration/registration_form.html => pytask/templates/registration/registration_form.html
rename : utils.py => pytask/utils.py
Diffstat (limited to 'parts/django/docs/howto/deployment/fastcgi.txt')
| -rw-r--r-- | parts/django/docs/howto/deployment/fastcgi.txt | 400 |
1 files changed, 400 insertions, 0 deletions
diff --git a/parts/django/docs/howto/deployment/fastcgi.txt b/parts/django/docs/howto/deployment/fastcgi.txt new file mode 100644 index 0000000..ea14b97 --- /dev/null +++ b/parts/django/docs/howto/deployment/fastcgi.txt @@ -0,0 +1,400 @@ +============================================ +How to use Django with FastCGI, SCGI, or AJP +============================================ + +.. highlight:: bash + +Although the current preferred setup for running Django is :doc:`Apache with +mod_wsgi </howto/deployment/modwsgi>`, many people use shared hosting, on +which protocols such as FastCGI, SCGI or AJP are the only viable options. In +some setups, these protocols may provide better performance than mod_wsgi_. + +.. admonition:: Note + + This document primarily focuses on FastCGI. Other protocols, such as SCGI + and AJP, are also supported, through the ``flup`` Python package. See the + Protocols_ section below for specifics about SCGI and AJP. + +Essentially, FastCGI is an efficient way of letting an external application +serve pages to a Web server. The Web server delegates the incoming Web requests +(via a socket) to FastCGI, which executes the code and passes the response back +to the Web server, which, in turn, passes it back to the client's Web browser. + +Like mod_python, FastCGI allows code to stay in memory, allowing requests to be +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. + +.. _mod_wsgi: http://code.google.com/p/modwsgi/ +.. _mod_perl: http://perl.apache.org/ +.. _mod_python: http://www.modpython.org/ + +.. admonition:: Why run code in a separate process? + + The traditional ``mod_*`` arrangements in Apache embed various scripting + languages (most notably PHP, Python and Perl) inside the process space of + your Web server. Although this lowers startup time -- because code doesn't + have to be read off disk for every request -- it comes at the cost of + memory use. For mod_python, for example, every Apache process gets its own + Python interpreter, which uses up a considerable amount of RAM. + + Due to the nature of FastCGI, it's even possible to have processes that run + under a different user account than the Web server process. That's a nice + 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_, a +Python library for dealing with FastCGI. Version 0.5 or newer should work fine. + +.. _flup: http://www.saddi.com/software/flup/ + +Starting your FastCGI server +============================ + +FastCGI operates on a client-server model, and in most cases you'll be starting +the FastCGI process on your own. Your Web server (be it Apache, lighttpd, or +otherwise) only contacts your Django-FastCGI process when the server needs a +dynamic page to be loaded. Because the daemon is already running with the code +in memory, it's able to serve the response very quickly. + +.. admonition:: Note + + If you're on a shared hosting system, you'll probably be forced to use + Web server-managed FastCGI processes. See the section below on running + Django with Web server-managed processes for more information. + +A Web server can connect to a FastCGI server in one of two ways: It can use +either a Unix domain socket (a "named pipe" on Win32 systems), or it can use a +TCP socket. What you choose is a manner of preference; a TCP socket is usually +easier due to permissions issues. + +To start your server, first change into the directory of your project (wherever +your :doc:`manage.py </ref/django-admin>` is), and then run the +:djadmin:`runfcgi` command:: + + ./manage.py runfcgi [options] + +If you specify ``help`` as the only option after :djadmin:`runfcgi`, it'll +display a list of all the available options. + +You'll need to specify either a :djadminopt:`socket`, a :djadminopt:`protocol` +or both :djadminopt:`host` and :djadminopt:`port`. Then, when you set up your +Web server, you'll just need to point it at the host/port or socket you +specified when starting the FastCGI server. See the examples_, below. + +Protocols +--------- + +Django supports all the protocols that flup_ does, namely fastcgi_, `SCGI`_ and +`AJP1.3`_ (the Apache JServ Protocol, version 1.3). Select your preferred +protocol by using the :djadminopt:`protocol=\<protocol_name\> <protocol>` option +with ``./manage.py runfcgi`` -- where ``<protocol_name>`` may be one of: +``fcgi`` (the default), ``scgi`` or ``ajp``. For example:: + + ./manage.py runfcgi protocol=scgi + +.. _flup: http://www.saddi.com/software/flup/ +.. _fastcgi: http://www.fastcgi.com/ +.. _SCGI: http://python.ca/scgi/protocol.txt +.. _AJP1.3: http://tomcat.apache.org/connectors-doc/ajp/ajpv13a.html + +Examples +-------- + +Running a threaded server on a TCP port:: + + ./manage.py runfcgi method=threaded host=127.0.0.1 port=3033 + +Running a preforked server on a Unix domain socket:: + + ./manage.py runfcgi method=prefork socket=/home/user/mysite.sock pidfile=django.pid + +.. admonition:: Socket security + + Django's default umask requires that the webserver and the Django fastcgi + process be run with the same group **and** user. For increased security, + you can run them under the same group but as different users. If you do + this, you will need to set the umask to 0002 using the ``umask`` argument + to ``runfcgi``. + +Run without daemonizing (backgrounding) the process (good for debugging):: + + ./manage.py runfcgi daemonize=false socket=/tmp/mysite.sock maxrequests=1 + +Stopping the FastCGI daemon +--------------------------- + +If you have the process running in the foreground, it's easy enough to stop it: +Simply hitting ``Ctrl-C`` will stop and quit the FastCGI server. However, when +you're dealing with background processes, you'll need to resort to the Unix +``kill`` command. + +If you specify the :djadminopt:`pidfile` option to :djadmin:`runfcgi`, you can +kill the running FastCGI daemon like this:: + + kill `cat $PIDFILE` + +...where ``$PIDFILE`` is the ``pidfile`` you specified. + +To easily restart your FastCGI daemon on Unix, try this small shell script:: + + #!/bin/bash + + # Replace these three settings. + PROJDIR="/home/user/myproject" + PIDFILE="$PROJDIR/mysite.pid" + SOCKET="$PROJDIR/mysite.sock" + + cd $PROJDIR + if [ -f $PIDFILE ]; then + kill `cat -- $PIDFILE` + rm -f -- $PIDFILE + fi + + exec /usr/bin/env - \ + PYTHONPATH="../python:.." \ + ./manage.py runfcgi socket=$SOCKET pidfile=$PIDFILE + +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 +documentation for instructions. + +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: + +.. code-block:: apache + + # 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 + +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: + +.. code-block:: apache + + <VirtualHost 12.34.56.78> + ServerName example.com + DocumentRoot /home/user/public_html + Alias /media /home/user/python/django/contrib/admin/media + RewriteEngine On + RewriteRule ^/(media.*)$ /$1 [QSA,L,PT] + RewriteCond %{REQUEST_FILENAME} !-f + RewriteRule ^/(.*)$ /mysite.fcgi/$1 [QSA,L] + </VirtualHost> + +.. _mod_rewrite: http://httpd.apache.org/docs/2.0/mod/mod_rewrite.html + +Django will automatically use the pre-rewrite version of the URL when +constructing URLs with the ``{% url %}`` template tag (and similar methods). + +lighttpd setup +============== + +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. + +.. _lighttpd: http://www.lighttpd.net/ + +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. + +Add the following to your lighttpd config file: + +.. code-block:: lua + + server.document-root = "/home/user/public_html" + fastcgi.server = ( + "/mysite.fcgi" => ( + "main" => ( + # Use host / port instead of socket for TCP fastcgi + # "host" => "127.0.0.1", + # "port" => 3033, + "socket" => "/home/user/mysite.sock", + "check-local" => "disable", + ) + ), + ) + alias.url = ( + "/media" => "/home/user/django/contrib/admin/media/", + ) + + url.rewrite-once = ( + "^(/media.*)$" => "$1", + "^/favicon\.ico$" => "/media/favicon.ico", + "^(/.*)$" => "/mysite.fcgi$1", + ) + +Running multiple Django sites on one lighttpd +--------------------------------------------- + +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:: + + # If the hostname is 'www.example1.com'... + $HTTP["host"] == "www.example1.com" { + server.document-root = "/foo/site1" + fastcgi.server = ( + ... + ) + ... + } + + # If the hostname is 'www.example2.com'... + $HTTP["host"] == "www.example2.com" { + server.document-root = "/foo/site2" + fastcgi.server = ( + ... + ) + ... + } + +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. + +Cherokee setup +============== + +Cherokee is a very fast, flexible and easy to configure Web Server. It +supports the widespread technologies nowadays: FastCGI, SCGI, PHP, CGI, SSI, +TLS and SSL encrypted connections, Virtual hosts, Authentication, on the fly +encoding, Load Balancing, Apache compatible log files, Data Base Balancer, +Reverse HTTP Proxy and much more. + +The Cherokee project provides a documentation to `setting up Django`_ with Cherokee. + +.. _setting up Django: http://www.cherokee-project.com/doc/cookbook_django.html + +Running Django on a shared-hosting provider with Apache +======================================================= + +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'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``: + +.. code-block:: apache + + AddHandler fastcgi-script .fcgi + RewriteEngine On + RewriteCond %{REQUEST_FILENAME} !-f + RewriteRule ^(.*)$ mysite.fcgi/$1 [QSA,L] + +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: + +.. code-block:: python + + #!/usr/bin/python + import sys, os + + # Add a custom Python path. + sys.path.insert(0, "/home/user/python") + + # Switch to the directory of your project. (Optional.) + # os.chdir("/home/user/myproject") + + # Set the DJANGO_SETTINGS_MODULE environment variable. + os.environ['DJANGO_SETTINGS_MODULE'] = "myproject.settings" + + from django.core.servers.fastcgi import runfastcgi + runfastcgi(method="threaded", daemonize="false") + +Restarting the spawned server +----------------------------- + +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, you can accomplish this +easily by using the ``touch`` command:: + + touch mysite.fcgi + +Serving admin media files +========================= + +Regardless of the server and configuration you eventually decide to use, you +will also need to give some thought to how to serve the admin media files. The +advice given in the :ref:`modpython <serving-the-admin-files>` documentation +is also applicable in the setups detailed above. + +Forcing the URL prefix to a particular value +============================================ + +Because many of these fastcgi-based solutions require rewriting the URL at +some point inside the Web server, the path information that Django sees may not +resemble the original URL that was passed in. This is a problem if the Django +application is being served from under a particular prefix and you want your +URLs from the ``{% url %}`` tag to look like the prefix, rather than the +rewritten version, which might contain, for example, ``mysite.fcgi``. + +Django makes a good attempt to work out what the real script name prefix +should be. In particular, if the Web server sets the ``SCRIPT_URL`` (specific +to Apache's mod_rewrite), or ``REDIRECT_URL`` (set by a few servers, including +Apache + mod_rewrite in some situations), Django will work out the original +prefix automatically. + +In the cases where Django cannot work out the prefix correctly and where you +want the original value to be used in URLs, you can set the +:setting:`FORCE_SCRIPT_NAME` setting in your main ``settings`` file. This sets the +script name uniformly for every URL served via that settings file. Thus you'll +need to use different settings files if you want different sets of URLs to +have different script names in this case, but that is a rare situation. + +As an example of how to use it, if your Django configuration is serving all of +the URLs under ``'/'`` and you wanted to use this setting, you would set +``FORCE_SCRIPT_NAME = ''`` in your settings file. |