Usage
=====

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

Depending on Django version, you will need to pick the correct template
variation - either for your application or for your Django project.

For example, to start a new Django project, using version 1.8 run the command::

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

Currently the following project templates are available:

- ``project-django-1.8``

Main difference when using one of the *Majic Django Templates* project templates
compared to regular, built-in Django project template is separation of settings
into base, and per-environment files (whereas stock Django has only one
``settings.py`` configuration file). You can read more about this in the next
section.


Common project template structure
---------------------------------

Despite having certain differences, all project templates share a common
structure and logic behind separation of settings files.

Each project template contains a number of distinct settings files.

At the very least, a base settings file (``settings/base.py``) is provided. This
file is used for specifying common configuration options that are shared across
all environments. This is a perfect place to specify things like installed
applications, or application-specific settings.

By default project templates come with additional environment-specific settings
files. These settings files build upon the base settings file
(``settings/base.py``) by importing all of the avaible settings from it. This
allows you to both add and override some of the settings from the base
file. Since they are just plain Python files, this means you can also do some
programatic manipulation of varible defined in base settings file.

The following environment-specific settings files are available:

- ``settings/development.py``, used for development environment running on
  developer's machine. Full debugging is enabled within this file, and if you
  run the application server against this file you should not expose it to the
  outside. In order to reduce effort during development, this settings file
  contains static credentials wherever possible.
- ``settings/testing.py``, used for testing environment.
- ``settings/staging.py``, used for staging environment.
- ``settings/production.py``, used for production environment.

.. note:
   The ``settings/testing.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``.

The following are the main items that are set on per-environment basis:

- Usernames.
- Environment-specific FQDNs and hostnames.
- Environment-specific URLs.

The only environment-specific settings that should be excluded from the
above-listed files are secrets and passwords. At the very least, this usually
involves database password, and Django's ``SECRET_KEY`` setting.

These credentials are best stored in a local ``credentials.py`` file, which
should be put into ``settings/`` directory, but excluded from version
control. Credentials file needs to have at minimum the following credentials
(variables) set within:

- ``SECRET_KEY``, which can be generated with the following one-liner::

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

- ``DATABASE_PASSWORD``, which should hold database password for the environment.


Project template for Django 1.8
-------------------------------

Project template can be found in sub-directory ``project-django-1.8``.

In order to get started with a project using this template, perform the
following steps:

1. Start your project using custom project template::

     django-admin startproject --template /path/to/majic-django-templates/project-django-1.8 myproject

2. Configure database in files ``myproject/myproject/settings/testing.py``,
   ``myproject/myproject/settings/staging.py``, and
   ``myproject/myproject/settings/production.py``.

   .. warning:
      Make sure not to touch database password in any of these files.

3. In order to make your life easier, it is recommended that you modify your
   Python virtual environments (you *are* using ``virtualenv``, aren't you?) to
   reference correct settings file via ``DJANGO_SETTINGS_MODULE`` environment
   variable. This can be easily done in file ``$VIRTUALENV/bin/postactivate``,
   just add a line (where ``ENVIRONMENT`` is the environment you the virtualenv
   belongs to, for example ``development``)::

     export DJANGO_SETTINGS_MODULE="myproject.settings.ENVIRONMENT"

   If you do not do this, you will need to be passing --settings to every Django
   command run - which can get very tedious very fast.

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.