.. _ref-deployment:

Deployment
==========

In short: 

- Create a ``local_settings.py`` alongside ``settings.py`` for your
  host-specific settings (like database connection, email, etc).
- Configure mod_wsgi or mod_python.
- Set up ``cron`` job for mailer and asynchronous notifications.

Using mod_wsgi
--------------

If you are using mod_wsgi, which we recommend, you will need to give it a
WSGI file. Here is a sample WSGI file that correctly sets up your ``sys.path``
to use all of the correct components::
    
    import os
    import sys
    
    # redirect sys.stdout to sys.stderr for bad libraries like geopy that uses
    # print statements for optional import exceptions.
    sys.stdout = sys.stderr
    
    from os.path import abspath, dirname, join
    from site import addsitedir
    
    path = addsitedir(abspath(join(dirname(__file__), "pinax", "libs", "external_libs")), set())
    if path:
        sys.path = list(path) + sys.path
        
    sys.path.insert(0, abspath(join(dirname(__file__), "pinax", "apps", "external_apps")))
    sys.path.insert(0, abspath(join(dirname(__file__), "pinax", "apps", "local_apps")))
    sys.path.insert(0, abspath(join(dirname(__file__), "pinax", "apps", "core_apps")))
    
    sys.path.insert(0, abspath(join(dirname(__file__), "pinax", "projects")))
    
    from django.core.handlers.wsgi import WSGIHandler
    
    os.environ["DJANGO_SETTINGS_MODULE"] = "complete_project.settings"
    
    application = WSGIHandler()

Using mod_python
----------------

If mod_python is your flavor we have provided the correct hooks for you to
use Pinax. Here is a sample Apache config that you can use::

    <Location "/">
        SetHandler python-program
        PythonHandler complete_project.deploy.modpython
        SetEnv DJANGO_SETTINGS_MODULE complete_project.settings
        PythonDebug On
        PythonPath "['/path/to/pinax/projects'] + sys.path"
    </Location>

.. note::

    It is important to note that you should pay careful attension to the
    value of ``PythonHandler`` above. It is *not* using
    ``django.core.handlers.modpython``. It is using a mod_python handler
    located in your project's ``deploy/`` directory. The reason why we have
    our own mod_python handler is because we need to setup the Pinax
    environment otherwise you will see failing imports.

Sending Mail and Notices
------------------------

Both mail messages and (some) notifications are queued for asynchronous
delivery. To actually deliver them you need to run

::
    
    ./manage.py send_mail
    
and

::
    
    ./manage.py emit_notices
    
on a frequent, regular basis.

Because failed mail will be deferred, you need an additional, less
frequency run of

::
    
    ./manage.py retry_deferred
    
We recommend setting up cron jobs similar to the following:
    
::
    
    * * * * * (cd /path/to/pinax; /usr/local/bin/python2.5 manage.py send_mail >> /path/to/pinax/cron_mail.log 2>&1)
    * * * * * (cd /path/to/pinax ; /usr/local/bin/python2.5 manage.py emit_notices >> /path/to/pinax/emit_notices.log 2>&1)
    
    0,20,40 * * * * (cd /path/to/pinax; /usr/local/bin/python2.5 manage.py retry_deferred >> /path/to/pinax/cron_mail_deferred.log 2>&1)

This runs ``send_mail`` and ``emit_notices`` every minute and ``retry_deferred`` every 20 minutes.


See also
--------

- `Pinax Setup and Deployment`_ by Greg Newman
- `Getting Started With Pinax`_ by Eric Holscher

.. _`Pinax Setup and Deployment`: http://www.20seven.org/journal/2008/09/pinax-setup-and-deploy.html
.. _`Getting Started With Pinax`: http://ericholscher.com/blog/2008/sep/18/getting-started-pinax/