Usage
=====

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


Starting a new project
----------------------

Depending on Django version, you will need to pick the correct template
variation.

The following projects templates are currently available:

- ``project-django-1.8``

For example, in order 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/ myproject

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. More about this in next section.


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

All project templates share a common structure and logic behind separation of
settings files. The main differences is that depending on Django version they
are intended to be used with, the templates may have slightly different settings
or settings syntax.


Settings
~~~~~~~~

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 varibles 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/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.

If you ever need to have some static files as part of the project itself, you
can easily do so by putting the files into project's static directory
(i.e. ``~/tmp/myproject/static/``). This is helpful when you want to overrides a
specific static file from some other application.


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.