outside. In order to reduce effort during development, this settings file

  contains static credentials wherever possible.

- ``settings/test.py``, used for testing environment.

- ``settings/staging.py``, used for staging environment.

- ``settings/production.py``, used for production environment.

.. note:

   The ``settings/test.py``, ``settings/staging.py``, and

   ``settings/production.py`` files are initially usually identical in content

   (when you start a new project).

This layout allows for a lot of flexibility, and makes it possible to also

easily introduce additional environments - just pick one of the shipped settings

file as starting point, and create a new environment's settings file. You can

also opt to rename a settings file to better suit your naming conventions. For

example, you may opt to rename ``settings/staging.py`` to

``settings/acceptance.py``.

Out of the box, the following options are set on per-environment basis:

- Debug configuration.

- List of project administrators and managers.

- Database configuration.

- Allowed hosts.

Options which are explicitly kept outside of both base and environment-specific

settings files are database password and Django's ``SECRET_KEY`` setting. The

only exception is the development environment where these values are hard-coded

(to be more precise, development environment out of the box uses ``sqlite3``, so

no need for database password).

Database password and ``SECRET_KEY`` are read from a local ``credentials.py``

file, which should be put into ``settings/`` directory. It should be noted that

``credentials.py`` should be explicitly excluded from version control systems.

In its basic form, ``credentials.py`` should look as follows::

  DATABASE_PASSWORD="your_db_password"

  SECRET_KEY="your_secret_key"

The secret key can easily be generated with the following one-liner::

    python -c "import random; print(''.join([random.SystemRandom().choice('abcdefghijklmnopqrstuvwxyz0123456789\!@#$%^&*(-_=+)') for i in range(50)]))"

Requirements

~~~~~~~~~~~~

Project templates contain a number of separate ``requirements.txt`` files that

are useful for keeping track of required packages in ``virtualenv`` across

multiple environments.

Out of the box, the following requirements files are created for you out of the

box:

- ``requirements/base.txt``, used as base for all environments.

- ``requirements/development.txt``, used for development environment.

- ``requirements/test.txt``, used for test environment.

- ``requirements/staging.txt``, used for staging environment.

- ``requirements/production.txt``, used for production environment.

As with the settings file, you can use the ``base.txt`` file for specifying

project requirements that are used in all environments. Out of the box this file

contains a single requirement - Django itself (with specific version listed that

matches the template).

Then, in case you need to have different packages installed in specific

environments, you can use one of the environment-specific requirements

files. For example, to install requirements needed for development environment,

you would run::

  pip install pip install requirements/development.txt

Serving of static and media files

---------------------------------

Out of the box, project templates will configure ``/static/`` as base URL for

static files, and ``/media/`` as base URL for media.

Root directories for locating static and media files are set-up to point to

parent directory of project (so, one level up from ``manage.py``), in

directories ``assets/static/`` and ``assets/media/``.

As an example, in case you create project in ``~/tmp/``, you would have

structure similar to:

- ``~/tmp/myproject/``

- ``~/tmp/myproject/manage.py``

- Many other files and directories under ``~/tmp/myproject/``

- ``~/tmp/assets/static/``

- ``~/tmp/assets/media/``

This way you can keep the assets (static and media files) outside of the project

code tree.

Working with the project

------------------------

When running ``manage.py`` commands for a project, Django by default expects all

settings to be found within the project's settings module. Specifically, it

expects them all to be present in the ``settings.py`` file.

As mentioned before, when using *Majic Django Templates*, this file is

split-up. When Django attempts to load all settings from the project's

``settings`` module, it will fail (since it will effectively be loading settings

from an empty ``__init__.py`` file).

Therefore, settings file must be explicitly specified for all Django commands,

as well as for running the project. There are two ways to do this.

One way is to pass the ``--settings`` option to every invocation of

``manage.py`` command. For example, in order to run the migrate command for

development environment, you would run::

  ./manage.py migrate --settings myproject.settings.development

The second way, is to make sure that the ``DJANGO_SETTINGS_MODULE`` environment

variable is set-up. Following the previous example, you could do something along

the lines of::

  export DJANGO_SETTINGS_MODULE="myproject.settings.development"

  ./manage.py migrate

Environment variable route is possibly the preferred way to do things, since it

will reduce possibility of making a mistake. It should be noted that for running

``django-admin`` commands you may need to temporarily unset the

``DJANGO_SETTINGS_MODULE`` environment variable.

If you happen to be using a virtual environment, you can easily set up the

post-activation script to set the ``DJANGO_SETTINGS_MODULE`` value.