diff --git a/docs/index.rst b/docs/index.rst index 35c7d0f0692b70b4963854f384e4212d29aaff2d..0a7a30d550ce85e91768cca8c78b082e753ad817 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -28,6 +28,7 @@ Contents: about installation + usage development diff --git a/docs/usage.rst b/docs/usage.rst index a49eb5c150dd7f25c79a8c5eca7ba9ee3e66a873..6a5a11a4fa7b5d042c1a031b51c76d99580ded6a 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -4,26 +4,119 @@ 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:: +Depending on Django version, you will need to pick the correct template +variation - either for your application or for your Django project. - django-admin startproject --template /path/to/majic-django-templates/project/ your_project_name +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 -Project template ----------------- +Currently the following project templates are available: -The template project can be found within the sub-directory ``project``. +- ``project-django-1.8`` -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. +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. -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. +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``