Skip to content

composable-settings.rst

Latest commit

 

History

History
173 lines (112 loc) · 6.55 KB

composable-settings.rst

File metadata and controls

173 lines (112 loc) · 6.55 KB

Composable settings

The ixc_django_docker.settings package includes many composable settings modules that can be combined as required.

The settings modules are included and combined via django-split-settings.

Think of settings as a hierarchy:

  • base settings are included from ixc_django_docker.settings for critical and optional but commonly needed configuration.
  • project settings are included from ixcproject.settings for project specific configuration, and they override base settings.
  • override settings are included from ixc_django_docker.settings and ixcproject.settings for environment specific configuration, and they override both base and project settings.
  • dotenv environment variables are sourced from .env.base, .env.DOTENV.secret and .env.local files, and they are available to Bash scripts, running processes and base, project and override settings.

To configure an ixc-django-docker project, specify the following environment variables:

BASE_SETTINGS

    A space separated list of *base* settings modules to be included from
    ``ixc_django_docker.settings``.

    Default: ``base.py compressor.py logentries.py storages.py whitenoise.py``  # Just enough to solve horizontal scaling and ephemeral infrastructure issues

PROJECT_SETTINGS

    A single settings module to be included from ``ixcproject.settings``.

    Default: ``base.py``

OVERRIDE_SETTINGS

    A single settings module to be included from
    ``ixc_django_docker.settings`` *and* ``ixcproject.settings``.

    Default: ``$DOTENV.py``

DOTENV

    The ``.env.$DOTENV.secret`` file to be sourced by ``entrypoint.sh``.

    Default: Undefined

WARNING: All settings modules should be specified as file system paths relative to the settings package they are to be included from, not dotted path module names.

How to specify environment variables

With Docker Compose or go.sh, you must create a .env.local file which specifies at least DOTENV and GPG_PASSPHRASE or TRANSCRYPT_PASSWORD.

With Docker Cloud, you must specify these in your stack file for every ixc-django-docker service.

All other environment variables can then be specified in .env.base and .env.$DOTENV.secret files.

NOTE: .env.local is sourced twice. Once to obtain the DOTENV and GPG_PASSPHRASE or TRANSCRYPT_PASSWORD variables that are required to decrypt .env.$DOTENV.secret, then again to override any conflicting environment variables.

Bundled base settings

  • base.py - Safe default settings, based on Django 1.8 LTS project template and checklist.

    NOTE: This settings module is required.

    TODO: Should we include it automatically, since it is required? Perhaps we need a base18.py and base111.py?

  • celery.py - Use Celery and Celery Beat for asynchronous and scheduled task processing.

  • celery_email.py - Use django-celery-email for asynchronous email delivery via Celery.

  • compressor.py - Use django-compressor to compile and compress CSS, JavaScript, Less, Sass, etc.

  • debug_toolbar.py - Enable django-debug-toolbar.

  • extensions.py - Use django-extensions for convenience and debugging (manage.py shell_plus, Werkzeug, etc.)

  • haystack.py - Use django-haystack with ElasticSearch backend for search.

  • logentries.py - Enable LogEntries integration for persistent log storage and aggregation. See Logging with LogEntries for more information.

    NOTE: Requires a LogEntries account and the LOGENTRIES_TOKEN environment variable.

  • master_password.py - Use django-master-password to accept a master password for any account.

    NOTE: Requires the MASTER_PASSWORD environment variable.

    WARNING: This is not recommended for production environments. When DEBUG=False, the master password must be strong and encrypted (see manage.py make_password).

  • nose.py - Use django-nose with nose-exclude and nose-progressive (temporarily disabled) when running tests.

  • post_office.py - Use django-post-office for asynchronous email delivery and logging.

    TODO: Remove this, now that we use django-celery-email?

  • redis_cache.py - Use python-redis-lock as the default cache backend, for performance and convenience.

    NOTE: Requires a Redis server and the REDIS_ADDRESS (HOST:PORT) environment variable.

  • sentry.py - Use Sentry for server error aggregation and alerts.

    NOTE: Requires a Sentry account or private instance and the SENTRY_DSN environment variable.

  • storages.py - Use django-storages to enable remote storage on AWS S3.

    NOTE: Requires an AWS S3 bucket and IAM user with appropriate permissions, and the MEDIA_AWS_ACCESS_KEY_ID, MEDIA_AWS_SECRET_ACCESS_KEY environment variables.

    NOTE: Requires the MEDIA_AWS_STORAGE_BUCKET_NAME environment variable, if your bucket is not named the same as your project slug.

  • whitenoise.py - Use whitenoise and ixc-whitenoise to serve static files and media.

Bundled override settings

  • develop.py - Enable DEBUG mode, relax security, etc.
  • test.py - Enable DEBUG mode, relax security, enable caching, configure test database, etc.
  • staging.py - Reconfigure logging, enable caching, etc.
  • production.py - Reconfigure logging, enable caching, reconfigure email backend (actually send emails), etc.