usage

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.