diff --git a/docs/usage.rst b/docs/usage.rst index 6a5a11a4fa7b5d042c1a031b51c76d99580ded6a..ad205757280d83d2fc975bb6491b7a1bd8890312 100644 --- a/docs/usage.rst +++ b/docs/usage.rst @@ -4,29 +4,38 @@ 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:: +Starting a new project +---------------------- - django-admin startproject --template /path/to/majic-django-templates/project-django-1.8/ your_project_name +Depending on Django version, you will need to pick the correct template +variation. -Currently the following project templates are available: +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 (whereas stock Django has only one -``settings.py`` configuration file). You can read more about this in the next -section. +into base, and per-environment files. More about this in next section. Common project template structure --------------------------------- -Despite having certain differences, all project templates share a common -structure and logic behind separation of settings files. +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. @@ -40,7 +49,7 @@ 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. +programatic manipulation of varibles defined in base settings file. The following environment-specific settings files are available: @@ -49,12 +58,12 @@ The following environment-specific settings files are available: 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/test.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 + The ``settings/test.py``, ``settings/staging.py``, and ``settings/production.py`` files are initially usually identical in content (when you start a new project). @@ -65,145 +74,94 @@ 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: +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. -- Usernames. -- Environment-specific FQDNs and hostnames. -- Environment-specific URLs. +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). -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. +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. -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: +In its basic form, ``credentials.py`` should look as follows:: -- ``SECRET_KEY``, which can be generated with the following one-liner:: + 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)]))" -- ``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. + +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 + + +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.