Source

django-environments / README

Full commit
django-environments
===================

Manage different settings for different locations (systems), like
local (your machine), development (shared development system), test,
staging/acceptance and production, with "maximum DRY".

Or, more generically: be able to refactor your settings as you like,
by simply "inheriting" from more generic settings using 'from ...
import'.

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``.
 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 the
    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 manage.py runserver with the correct settings.

Using Apache mod_wsgi
=====================

Should you wish to use the local settings in for instance
``settings/env/staging.py``, simply copy the ``mysite/deploy/example.wsgi``
to ``mysite/deploy/staging.wsgi``, or make staging.wsgi a symlink. Then add
something like this to your httpd.conf::

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

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

You can add specific site packages to 

Automatic generation of local wsgi links and settings file
==========================================================

Alternatively, 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 symbolic link deploy/local.wsgi 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. The local.py file will be pyc-compiled
automatically. 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; 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 an '.sh'
   extension.

Remarks
=======

 * ``urls.py`` is just there to demonstrate the ``SERVE_MEDIA`` setting.
 * ``manage.py`` is just there to make this a complete Django project.