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`` - ``project-django-1.10`` 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. Version specifics ~~~~~~~~~~~~~~~~~ This section outlines any specific differences between project templates. These are mostly present due to differences in Django itself. - ``project-django-1.10`` sets-up password validation out of the box for all environments except the development. In development environment the password validation is explicitly disabled to allow short passwords (which should result in faster develpment times as well). ``project-1.8.0`` does not have this option enabled out of the box.