.. _deployment:

==========
Deployment
==========

In short:

 * Create a ``local_settings.py`` alongside ``settings.py`` for your
   host-specific settings (like database connection, email, etc).
 * Configure your WSGI or FastCGI server.

All projects come with the deployment files to properly run your Pinax project
in a production environment. These are located in the ``deploy/`` directory
of your project.

Using mod_wsgi
==============

Here is a basic configuration for Apache (assuming you are using Python 2.7)::

    WSGIDaemonProcess mysite python-path=/path/to/mysite-env/lib/python2.7/site-packages
    WSGIProcessGroup mysite
    
    WSGIScriptAlias / /path/to/project/wsgi.py
    <Directory /path/to/project>
        Order deny,allow
        Allow from all
    </Directory>

The above configuration will likely need to be modified before use. Most
specifically make sure the ``python-path`` option points to the right Python
version. We encourage you to read about `WSGIDaemonProcess`_ to learn more
about what you can configure.

.. _WSGIDaemonProcess: http://code.google.com/p/modwsgi/wiki/ConfigurationDirectives#WSGIDaemonProcess

Using gunicorn
==============

Install gunicorn_ in your environment (best to add it to your requirements
file) and run ``gunicorn``::

    (mysite-env)$ pip install gunicorn
    (mysite-env)$ gunicorn --workers=2 --bind=127.0.0.1:8000 wsgi:application

This assumes your current working directory is your project root (``wsgi``
must be importable from where you are). Running the example shown above as-is
will not be sufficient for a production website. You will need to daemonize
the gunicorn processes and supervise them. Please refer to
`gunicorn documentation`_ for more information.

.. _gunicorn: http://gunicorn.org/
.. _gunicorn documentation: http://gunicorn.org/deploy.html

Using FastCGI
=============

To use FastCGI (including SCGI or AJP) you must install `flup`_. This can be
done by using ``pip``::

    pip install flup

Once installed, you can use Django's built-in ``runfcgi`` management command
to run a server. For example::

    python manage.py method=threaded host=127.0.0.1 port=3033

You can learn much more about ``runfcgi`` from the Django documentation on
`FastCGI deployment`_.

.. _flup: http://trac.saddi.com/flup
.. _FastCGI deployment: https://docs.djangoproject.com/en/1.3/howto/deployment/fastcgi/

Media files
===========

During development media files were handled for you. Running a production
Pinax project it is **strongly** recommeneded you do not rely on
``SERVE_MEDIA = True``. By default, ``SERVE_MEDIA`` is set to ``DEBUG`` which
likely means moving to production will turn off ``SERVE_MEDIA``.

Pinax, by default, sets ``STATIC_ROOT`` and ``MEDIA_ROOT`` to directories
within the same directory (``site_media``). This is very beneficial to running
a production Pinax site as you can configure your web server to serve files
from a single directory.

To collect all your static files into ``STATIC_ROOT`` for your web server to
serve run::

    (mysite-env)$ python manage.py collectstatic

nginx
-----

::

    server {
        ...
        
        location /site_media {
            alias /path/to/site_media;
        }
    }

Apache
------

::

    <VirtualHost *:80>
        ...
        
        Alias /site_media/ /path/to/site_media/
        
    </VirtualHost>