Source

django-environments / README

django-environments
===================

Manage different Django settings within a project, and easily switch
between them. Different settings can be helpful either on a single
computer, but django-environments is mostly intended for use on
different system environments, such as development, test, staging/acceptance
and production, all with "maximum DRY™".

On the command line, you specify your project and settings using
environment variables. When you run your application via WSGI, a
naming convention determines which settings to use based on the name
of the WSGI file. All this helps to minimize the number of code
changes and other file updates when working across different
environments.

Django-environments moves the ``settings.py`` to a settings package,
and suggests a settings inheritance model, which you can adhere to
as much as you like. Simply "inherit" from more generic settings
using ``from ... import *``, and overrule - see the provided examples.
If you'd rather use a "composition" model (import settings not just
from base settings "above", but also "from the side"), that's also
fine.

Compatibility with Python < 2.6
-------------------------------

In the example settings files, ``from .. import *`` is used. You will
need to change this to ``from <project>.settings import *`` for older
versions of Python. The downside is that you will have to include
the project name in your settings, which is a violation of the DRY
principle that django-environments tries to live by.

Compatibility with virtualenv
-----------------------------

Please note django-environments can be nicely used together with
virtualenv, especially virtualenvwrapper's ``bin/postactivate`` script.

Getting Started
---------------

This is a fully working Django project; you can copy files from it
as needed to your own projects. To get django-environments working
by itself, do the following:

1. Copy scripts/initenv_example to scripts/initenv.
2. Edit initenv and set ``PROJECT_ROOT``, ``DJANGO_PROJECT`` (always a
   subdirectory of ``PROJECT_ROOT``) and ``DJANGO_SETTINGS`` (simply
   changing ``PROJECT_ROOT`` should be enough for fresh checkouts, btw).
3. Activate the environment using ``source scripts/initenv``.
4. When using virtualenv with virtualenvwrapper, you can do either
   ``source <path-to-project>/scripts/initenv`` from ``bin/postactivate``,
   or simply use your initenv's contents inside postactivate. 
   Alternatively, you may also symlink ``bin/postactivate`` to your
   initenv script.

If everything works okay, the following shell aliases are created:

 * ``cdroot`` - go to project root.
 * ``cdjango`` - go to Django project root (one lower than project root).
 * ``runserver`` - perform ``django-admin.py runserver``.
 * ``syncdb`` - perform ``django-admin.py syncdb``.

Using Apache mod_wsgi
---------------------

Should you wish to use the settings in for instance
``settings/env/staging.py``, simply copy the example
``mysite/deploy/development.wsgi`` to ``mysite/deploy/staging.wsgi``,
or make staging.wsgi a symlink (if your Apache configuration allows
it, which is normally the case). Next, add something like this to
your httpd.conf::

    WSGIScriptAlias / /Users/spanky/repos/django-environments/mysite/deploy/staging.wsgi

And restart Apache. The identifier 'staging' in staging.wsgi will
automatically make sure settings.env.staging is used. Create other
.wsgi files for other environment settings.

Refer to the source of the provided WSGI script to see how specific
directories, like a virtualenv site-packages directory, can be
prepended to sys.path, overruling standard Python environment settings.

Automatic generation of local WSGI links and settings file
----------------------------------------------------------

If you want your WSGI setup done as quickly as possible, activate an
environment - either directly via your ``scripts/initenv`` or through
virtualenv - and execute ``scripts/setup_local_wsgi.sh <environment>``, e.g.::

    $ scripts/setup_local_wsgi.sh staging

This will create a ``deploy/local.wsgi`` symbolic link to staging.wsgi and
will create a ``settings/env/local.py`` with default contents for a given
environment. Now, you only need to update settings.env.local with those
settings you want to keep absolutely local, like those containing
user ids and passwords. Keep in mind the script will overwrite exiting
local.py settings files!

Directories
-----------

 * The ``mysite/settings`` directory replaces ``settings.py`` and contains
   the default settings in ``generic.py``, whose contents are
   imported in ``__init__.py``.
 * The ``mysite/settings/env`` directory contains the different settings
   files for every environment.
 * All .wsgi files in the ``mysite/deploy`` folder are normally
   equal, except for the ``sys.path`` configuration. Their respective
   filenames are used to determine which settings to import. If
   your Apache configuration allows it, you could use symlinks
   instead of copies.
 * The scripts directory contains the shell scripts intended to be
   sourced with the ``source`` command, unless they have a '.sh'
   extension.

Remarks
-------

 * ``urls.py`` is just there to demonstrate the ``SERVE_MEDIA`` setting.
 * ``manage.py`` is removed as the generated default ignores
   $DJANGO_SETTINGS_MODULE, simply importing 'settings' instead.