projects and applications, with some added flexibility and utilities for

deployments in multiple environments.

better control with personalised templates.

* Project templates for multiple version of Django. Supports multiple

  environment configurations (development, testing, production). Each

  environment builds upon a common configuration to provide the required tools

  and layout.

Development

===========

This section covers some of the basic steps and guidelines when doing

"development" of *Majic Django Templates*. This refers to updating the templates

and adding support for new Django versions, and should not be confused with

actual Django development that is based on templates.

Environment

-----------

For development purposes, it is recommended to have a dedicated Python virtual

environment.

For example, let's say that *Majic Django Templates* has been cloned in

directory ``~/majic-django-templates``. You would simply create a new virtual

environment, and set its home path to point to cloned repository::

  mkvirtualenv majic-django-templates -a ~/majic-django-templates

The virtual environment allows you to install the necessary Django versions

without affecting the rest of the system.

Once you are in the virtual environment, you may want to update ``pip`` and

``setuptools`` to have a couple of more up-to-date features available when

installing the packages::

  workon majic-django-templates && pip install -U pip setuptools

Adding project template for new Django release

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

Since Django follow semantic versioning, project template needs to be added for

every new major or minor release of Django.

This is just a rough outline of what needs to be done.

.. warning:

   All values like package versions etc are provided as examples. Make sure to

   update them before running the commands.

1. Start off by activating your virtual environment::

     workon majic-django-templates

2. Install latest patch release of targeted Django version, removing any

   currently installed version::

     pip install -U Django~=1.8.0

3. Start a new Django project using a unique string as project name. This name

   will not be used for the final product, it merely lets you locate certain

   parts of the file that need to be changed in order to use templated project

   name::

     django-admin startproject abcdef

4. Replace placeholder project name with proper Django template variable::

     find abcdef/ -type f -exec sed -i -e 's/abcdef/{{ project_name }}/' '{}' \;

5. Set-up the project settings to be a Python module and move the current set of

   settings to be the base configuration::

     mkdir abcdef/abcdef/settings/

     touch abcdef/abcdef/settings/__init__.py

     mv abcdef/abcdef/settings.py abcdef/abcdef/settings/base.py

6. Set-up settings file for development environment. It should default to using

   SQLite3, debugging should be fully enabled, and secret key should be static,

   coming from auto-generated value from ``django-admin startproject`` command.

   .. warning:

      Pay special care that parameters listed in this file make sense with your

      Django version. For example, debugging options have been known to change

      in Django.

   :file:`abcdef/abcdef/settings/development.py`

   ::

      # Development environment settings for project {{ project_name }}.

      # Import the base settings.

      from .base import *

      # Credentials in development environment are static.

      SECRET_KEY="{{ secret_key }}"

      # Enable debugging in development environment.

      DEBUG = True

      for template_config in TEMPLATES:

          template_config['OPTIONS']['debug']=True

      # Site administrators and managers.

      ADMINS = (

          # ('Your Name', 'your_email@example.com'),

      )

      MANAGERS = ADMINS

      # Use SQLite3 for simplicity in development environment.

      DATABASES = {

          'default': {

              'ENGINE': 'django.db.backends.sqlite3',

              'NAME': 'development.sqlite3',

              'USER': '',

              'PASSWORD': '',

              'HOST': '',

              'PORT': '',

          }

      }

7. Set-up settings files for **testing**, **staging**, and **production**

   environments. These should be identical, except for the header (which should

   clearly identify the environment).

   .. warning:

      Pay special care that parameters listed in this file make sense with your

      Django version.

   :file:`abcdef/abcdef/settings/ENVIRONMENT.py`

   ::

      # ENVIRONMENT environment settings for project {{ project_name }}.

      # Import the base settings.

      from .base import *

      # Import credentials.

      try:

          from .credentials import DATABASE_PASSWORD

      except ImportError:

          raise ImproperlyConfigured("Please configure DATABASE_PASSWORD in credentials.py.")

      try:

          from .credentials import SECRET_KEY

      except ImportError:

          raise ImproperlyConfigured("Please configure SECRET_KEY in credentials.py.")

      # Disable debugging.

      DEBUG = False

      for template_config in TEMPLATES:

          template_config['OPTIONS']['debug']=False

      # Site administrators and managers.

      ADMINS = (

          # ('Your Name', 'your_email@example.com'),

      )

      MANAGERS = ADMINS

      # Database configuration.

      DATABASES = {

          'default': {

              'ENGINE': 'django.db.backends.mysql',

              'NAME': '{{ project_name }}',

              'USER': '{{ project_name }}',

              'PASSWORD': DATABASE_PASSWORD,

              'HOST': '127.0.0.1',

              'PORT': '',

          }

      }

      # Hostnames/FQDNs considered valid for accessing the installation.

      ALLOWED_HOSTS = []

8. Further customisations will depend on Django version being used. At the very

   least take the following guidelines into consideration:

   - Anything representing a secret/password should only be explicitly specified

     in ``development.py``. In all other settings files the parameter should be

     removed, and should be instead imported from ``credentials`` module.

   - Introduce explicit checks for existence of imported variables from

     credentials module. This will save you in the long run in case of

     misconfiugurations of credentials (and things like typos).

   - Remove credentials/secrets from ``base.py``.

   - Remove debugging options from ``base.py``.

   - Remove things like allowed hosts from ``base.py``.

   - Remove database configuration from ``base.py``.

   - Configure things like media/static URLs and media/static roots. It is

     recommended to use dedicated assets directory for those, lying one level

     above the project root. A convenient way to calculate assets directory

     dynamically is (put this somewhere in ``base.py``)::

       # Determine assets directory location.

       ASSETS_ROOT = os.path.normpath(os.path.join(BASE_DIR, "assets"))

     Afterawards you can have something similar to the following snippet at the

     end of ``base.py``::

       # URLs for serving the static and media files.

       STATIC_URL = '/static/'

       MEDIA_URL = '/media/'

       # Absolute filesystem path to directory that will hold user-uploaded

       # files.

       MEDIA_ROOT = os.path.normpath(os.path.join(ASSETS_ROOT, "media"))

       # Absolute filesystem path to directory that will hold static files.

       STATIC_ROOT = os.path.normpath(os.path.join(ASSETS_ROOT, "static"))

       # Additional locations for static files. Useful for project-wide overrides of

       # default static files.

       STATICFILES_DIRS = (

           os.path.normpath(os.path.join(BASE_DIR, "static")),

       )

9. At this point you need to be a bit more creative. Depending on Django

   version, you may need to isolate different settings to be part of the base

   settings file, defined in development settings file etc.

10. Update the comments in all settings files to be more informational. If there

    are existing project templates, you may want to have a look at those to get

    a good idea what should be written.

11. Rename the directories::

      mv abcdef/abcdef/ abcdef/project_name

      mv abcdef/ project-django-1.8

12. Create usage instructions for the new project template. It is important to

    do so even if it duplicates other instructions since different versions of

    Django can have both subtle and important differences in how they are

    configured. Instructions should cover how the project is started, layout of

    directories and settings files, as well as useful information on how to have

    the system running when used in testing/staging/production environment via

    Gunicorn.

projects and applications, with some added flexibility and utilities for

deployments in multiple environments.

   development

All you need to do in order to use Majic Django Templates is to clone the git

repository. At time of this writing, there are no official releases, and you

should simply use the ``HEAD`` on ``master`` branch.

In order to use the templates, you will need a supported version of Django.

Project templates are supplied for the following Django versions::