Usage
=====

*Majic Django Templates* are utilised through the ``django-admin startproject``
and ``django-admin startapp`` commands.

To start a new Django project, run the command::

  django-admin startproject --template /path/to/majic-django-templates/project/ your_project_name


Project template
----------------

The template project can be found within the sub-directory ``project``.

Projects based on this template will have practically the same structure as the
stock Django template, with the main difference coming in the way the settings
are laid out.

Under stock Django project, there is a single ``settings.py`` file, containing
all the project and application configuration.

Under *Majic Django Templates* project template, this file is split into
multiple configuration files, allowing better reuse and separation of settings
and credentials between multiple environments.

Once you create a new project based on this template, in the project's directory
(at the same level as the ``manage.py`` file), a directory called ``settings``
is created instead of ``settings.py.`` Within this directory, the following
files are present:

* ``base.py`` provides a place to define common configuration options that would
  be shared amongst all of the different environments the project is deployed
  in. All of the other environment-specific configuration files will import all
  settings from this one, and build upon them. This is the right place to define
  your project's applications, common application settings, middlewares etc.
* ``sample_credentials.py`` provides an example on how the ``credentials.py``,
  which is environment-specific, should look like in order to be able to run a
  project. This file is mainly used for defining things like database passwords,
  ``SECRET_KEY`` etc (that is any sort of credentials that should not be shared).
* ``development.py`` comes with some additional settings which are well-suited
  for the development environments. This mainly revolves around using the
  ``sqlite3`` database, and enabling debugging.
* ``testing.py`` should be used for deploying the project in a testing
  environment. It should be noted that it is a good idea to have this
  configuration as close to the production one as possible, but the separate
  file is provided for easier customisation for a test environment. Things like
  database settings will probably differ between the two environments. It may
  also be necessary to enable some custom settings in test environment that
  might not be desirable to enable in development environment (for example
  debugging).
* ``production.py`` is used for deploying the project in a production
  environment. You should be very careful not to mess this file up, and make
  sure that things like debugging etc are turned off (unless you really, really
  need it in development environment).

There is very little in special variables used in the listed configuration
files. You can practically specify any Django or Django application
configuration where you wish to. There are only two special variables that are
project template-specific - ``DATABASE_PASSWORDS`` and ``SECRET_KEY``.

The ``SECRET_KEY`` must be specified in the ``credentials.py`` file, and its
syntax and meaning is the same as described in Django documentation.

The ``DATABASE_PASSWORDS`` is a dictionary, where keys are the database names,
and values are the corresponding passwords.

For example, let's say you define two databases for Django in ``production.py``
(in the Django ``DATABASES`` variable). Following the template layout, you would
make it look something similar to::

  .. highlight:: python

     DATABASES = {
         'database1': {
         'ENGINE': 'django.db.backends.mysql',
         'NAME': 'database1',
         'USER': 'database1_user',
         'PASSWORD': DATABASE_PASSWORDS['database1'],
         'HOST': '127.0.0.1',
         'PORT': '',
         },
         'database2': {
         'ENGINE': 'django.db.backends.mysql',
         'NAME': 'database2',
         'USER': 'database2_user',
         'PASSWORD': DATABASE_PASSWORDS['database2'],
         'HOST': '127.0.0.1',
         'PORT': '',
         }
    }


Subsequently, when deploying the production environment, you would create the
``credentials.py`` file in the same directory with the following content::

  .. highlight:: python

     DATABASE_PASSWORDS['database1']="database1_password
     DATABASE_PASSWORDS['database2']="database2_password

.. warning:: Make sure that the ``credentials.py`` is never part of your version
             control system history! It is highly recommended to keep this file
             in ``.gitignore``, ``.hgignore``, or whatever the equivalent of
             your version control system is!

In order to run your Django project with different settings, you would use one
of the following commands (depending on which environment you want to run)::

  python manage.py runserver --settings your_project_name.settings.development
  python manage.py runserver --settings your_project_name.settings.testing
  python manage.py runserver --settings your_project_name.settings.production

If using ``virtualenv``, you may want to set the ``DJANGO_SETTINGS_MODULE``
environment variable in it to make your life easier.