Configuring Molly
=================

Understanding the Config
------------------------

.. note:: This covers advanced topics and are not needed to get a simple Molly
          install going. We'd recommend coming back to this later, if you need
          to.

The settings file itself is a standard Django settings file, which is documented
in the `settings overview in the Django documentation <http://docs.djangoproject.com/en/1.2/topics/settings/>`_,
with the addition of some extra settings which configure Molly itself.

Some of the Django settings must be configured in particular ways for Molly to
operate as desired. These are listed below.

Preamble
^^^^^^^^

At the top of the Molly settings files we import some required definitions
for use later on in the file::

    from oauth.oauth import OAuthSignatureMethod_PLAINTEXT
    import os.path, imp
    from molly.conf.settings import Application, extract_installed_apps, Authentication, ExtraBase, Provider
    from molly.utils.media import get_compress_groups

We also define two variables which are used throughout, one to refer to the
location Molly is installed, and the second to refer to the location at which
the site lives::

    molly_root = imp.find_module('molly')[1]
    project_root = os.path.normpath(os.path.dirname(__file__))


Required Django settings
^^^^^^^^^^^^^^^^^^^^^^^^

The following settings are all required by the Molly project, but can be
configured freely for Molly to operate normally

* `ADMINS <http://docs.djangoproject.com/en/dev/ref/settings/#admins>`_
  by default the people defined here will receive logging e-mails and cronjob output
* `ADMIN_MEDIA_PREFIX <http://docs.djangoproject.com/en/dev/ref/settings/#admin-media-prefix>`_
* `DATABASES <http://docs.djangoproject.com/en/dev/ref/settings/#databases>`_
  note that the database engine should be set to an engine in
  ``django.contrib.gis``; PostGIS is recommended: ``django.contrib.gis.db.backends.postgis``
* `DEBUG <http://docs.djangoproject.com/en/dev/ref/settings/#debug>`_
* `LANGUAGE_CODE <http://docs.djangoproject.com/en/dev/ref/settings/#language-code>`_
* `LANGUAGES <http://docs.djangoproject.com/en/dev/ref/settings/#languages>`_ - this
  is the list of languages which Molly will display to its users as selectable. If
  not set, this will default to Django's default, which is probably not what you want.
* `LOCALE_PATHS <https://docs.djangoproject.com/en/dev/ref/settings/#locale-paths>`_ - this
  is where Molly will find any translation files you have prepared
* `MANAGERS <http://docs.djangoproject.com/en/dev/ref/settings/#managers>`_
  Molly gives this setting no special meaning, so it is recommended you set
  this to the same as ADMINS
* `SITE_ID <http://docs.djangoproject.com/en/dev/ref/settings/#site-id>`_
  unused in most situations, so leave at 1
* `STATIC_ROOT <http://docs.djangoproject.com/en/dev/ref/settings/#static-root>`_
  this is the path to where on disk media for your site is served from. It
  should be an empty directory, which is populated during the build process.
* `STATIC_URL <http://docs.djangoproject.com/en/dev/ref/settings/#static-url>`_
  this is the URL to the location where your media is served from (note that
  Django does not serve media in non-development mode, but relies on your web
  server to do it, for more information see :doc:`deploying`).
* `TEMPLATE_DEBUG <http://docs.djangoproject.com/en/dev/ref/settings/#template-debug>`_
* `TIME_ZONE <http://docs.djangoproject.com/en/dev/ref/settings/#time-zone>`_

Required Settings for Molly
^^^^^^^^^^^^^^^^^^^^^^^^^^^

The following settings are all standard Django settings, but must be configured
in a particular way for Molly to operate correctly:

`CSRF_FAILURE_VIEW <https://docs.djangoproject.com/en/dev/ref/settings/#csrf-failure-view>`_
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

To render a nice page when a CSRF validation failure occurs, Molly ships with a
default page for these circumstances. Django must be told to use this page::

    CSRF_FAILURE_VIEW = 'molly.utils.views.CSRFFailureView'

`INSTALLED_APPS <http://docs.djangoproject.com/en/dev/ref/settings/#installed-apps>`_
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

This must be defined after the APPLICATIONS_ setting. This setting is used to
inform Django which Molly apps are loaded, as well as any non-Molly applications
that are being used. Molly provides one Django application and has dependencies
on other Django applications which must be included. INSTALLED_APPS_ must
therefore be at least::

    INSTALLED_APPS = extract_installed_apps(APPLICATIONS) + (
        'django.contrib.auth',
        'django.contrib.admin',
        'django.contrib.contenttypes',
        'django.contrib.sessions',
        'django.contrib.sites',
        'django.contrib.gis',
        'django.contrib.comments',
        'molly.batch_processing',
        'django.contrib.staticfiles',
        'pipeline',
        'south',
    )

With any additional non-Molly apps being added to the bottom of the list.

Logging configuration should be done the same way it is done for every `Django project <https://docs.djangoproject.com/en/dev/topics/logging/>`.

`MIDDLEWARE_CLASSES <http://docs.djangoproject.com/en/dev/ref/settings/#middleware-classes>`_
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

The setup of middleware can vary between particular installations, however for
getting started, the default value below will suffice. More advanced users
should refer to the `Django reference <http://docs.djangoproject.com/en/dev/ref/settings/#middleware-classes>`_

At the very least, this setting must include
``molly.wurfl.middleware.WurflMiddleware`` as the first value and then at any
point in the list ``molly.auth.middleware.SecureSessionMiddleware`` and
``molly.url_shortener.middleware.URLShortenerMiddleware``, as well as Django's
default middleware.

In order to enable geolocation functionality in Molly, you must enable
``molly.utils.middleware.LocationMiddleware``.

A typical setup may look like this::

    MIDDLEWARE_CLASSES = (
        'molly.wurfl.middleware.WurflMiddleware',
        'django.middleware.common.CommonMiddleware',
        'django.contrib.sessions.middleware.SessionMiddleware',
        'molly.utils.middleware.CookieLocaleMiddleware',
        'molly.utils.middleware.ErrorHandlingMiddleware',
        'molly.utils.middleware.LocationMiddleware',
        'django.contrib.auth.middleware.AuthenticationMiddleware',
        'molly.auth.middleware.SecureSessionMiddleware',
        'molly.url_shortener.middleware.URLShortenerMiddleware',
        'django.middleware.csrf.CsrfViewMiddleware',
    )

`ROOT_URLCONF <http://docs.djangoproject.com/en/dev/ref/settings/#root-urlconf>`_
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Molly will automatically create a urlconf based on your loaded applications,
however, you can override this to a custom one if you wish. To use the
default urlconf that comes with Molly set this setting like so::

    ROOT_URLCONF = 'molly.urls'

`STATICFILES_DIRS <http://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/#std:setting-STATICFILES_DIRS>`_
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

This is a list of locations where media is collected from to be served. Assuming
that you have a folder called ``site_media`` which contains your custom media
(this is created in the default layout by the installer), and you wish to fall
through to Molly's media if required, then the following setting should
suffice::

    STATICFILES_DIRS = (
        ('', os.path.join(project_root, 'site_media')),
        ('', os.path.join(molly_root, 'media')),
        ('markers', MARKER_DIR),
    )

Note that the final lines (markers) is required for slippy maps to correctly
display markers.

`TEMPLATE_CONTEXT_PROCESSORS <http://docs.djangoproject.com/en/dev/ref/settings/#TEMPLATE_CONTEXT_PROCESSORS>`_
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

Like MIDDLEWARE_CLASSES_, this can vary between installations, but the
`Django reference <http://docs.djangoproject.com/en/dev/ref/settings/#template-context-processors>`_
is a good starting point for more advanced users. To get started, the typical
value below should suffice.

If configuring this directly, then it is recommended you use the
``molly.utils.context_processors.ssl_media`` context processor instead of
Django's ``django.core.context_processors.media``, especially if you're serving
media from a separate server (for more information, read
`this blog post <http://mobileoxfordtech.posterous.com/33885695>`_).
The following context processors are required for correct operation of Molly in
most settings:

* ``molly.wurfl.context_processors.wurfl_device``
* ``molly.wurfl.context_processors.device_specific_media``
* ``molly.geolocation.context_processors.geolocation``
* ``molly.utils.context_processors.full_path``

If you wish to use Google Analytics, ``molly.utils.context_processors.google_analytics`` is useful.

A typical setup looks like this::

    TEMPLATE_CONTEXT_PROCESSORS = (
        'django.core.context_processors.auth',
        'django.core.context_processors.debug',
        'django.core.context_processors.request',
        'molly.utils.context_processors.languages',
        'molly.utils.context_processors.ssl_media',
        'django.contrib.messages.context_processors.messages',
        'molly.wurfl.context_processors.wurfl_device',
        'molly.wurfl.context_processors.device_specific_media',
        'molly.geolocation.context_processors.geolocation',
        'molly.utils.context_processors.full_path',
        'molly.utils.context_processors.google_analytics',
        'molly.utils.context_processors.site_name',
        'django.core.context_processors.csrf',
    )

`TEMPLATE_DIRS <http://docs.djangoproject.com/en/dev/ref/settings/#template-dirs>`_
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

These are the directories Django looks in for templates, in order of searching.
At it's most minimal, this needs to contain the path to Molly's templates folder,
but in most cases will also need to include the path to the folder where
templates specific to your deployment (the ones that override the default
templates) are being held. Using the shorthand paths set in the preamble_, and
assuming that your templates are stored in a ``templates/`` folder in your
deployment, the following is typical::

    TEMPLATE_DIRS = (
        os.path.join(project_root, 'templates'),
        os.path.join(molly_root, 'templates'),
    )

`TEMPLATE_LOADERS <http://docs.djangoproject.com/en/dev/ref/settings/#template-loaders>`_
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

This sets how Django looks for templates when rendering a view. This must
include Molly's custom template loader, and in almost all circumstances should
be set to the following value::

    TEMPLATE_LOADERS = (
        'django.template.loaders.filesystem.load_template_source',
        'django.template.ldjanoaders.app_directories.load_template_source',
        'django.template.loaders.eggs.load_template_source',
        'molly.utils.template_loaders.MollyDefaultLoader'
    )


`USE_18N <http://docs.djangoproject.com/en/dev/ref/settings/#use-i18n>`_
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

This settings enables Django's i18n support. As Molly has full i18n support, it
is recommended you set this to True::

    USE_I18N = True

`django-compress Settings <http://code.google.com/p/django-compress/wiki/Configuration>`_
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""

In order to deliver minified CSS and JavaScript, Molly uses
`a fork of django-compress <https://github.com/mikelim/django-compress>`_, which
must be configured appropriately.

The following settings will make this "just work" with Molly::

    PIPELINE_CSS, PIPELINE_JS = get_compress_groups(STATIC_ROOT)
    PIPELINE_AUTO = False
    PIPELINE_VERSION = True
    PIPELINE_CSS_COMPRESSOR = 'molly.utils.compress.MollyCSSFilter'
    PIPELINE_JS_COMPRESSOR = 'pipeline.compressors.jsmin.JSMinCompressor'

Celery settings
^^^^^^^^^^^^^^^
.. versionadded:: 1.4

We include a few sane-defaults for running Celery. These are::

    BROKER_URL = "amqp://molly:molly@localhost:5672//"
    CELERYBEAT_SCHEDULER = "djcelery.schedulers.DatabaseScheduler"
    CELERYD_CONCURRENCY = 1
    CELERY_RETRY_DELAY = 3 * 60
    CELERY_MAX_RETRIES = 3

The only setting you should worry about here is the `BROKER_URL`. This setting
is passed from Celery to the transport layer library Kombu, which has excellent
`documentation for the possible broker options`__ and their limitations. The
default we provide will attempt to use RabbitMQ with vhost `molly`, on
`localhost`, connecting as user `molly`.

__ http://ask.github.com/kombu/userguide/connections.html#urls

Remaining options are best explained in the `Celery documentation`__.

__ http://docs.celeryproject.org/en/2.4/configuration.html

Molly settings
^^^^^^^^^^^^^^

The following settings are additional to the Django configuration and configure
Molly directly.

APPLICATIONS
""""""""""""

This setting defines your Molly applications and how they are configured. It
should consists of a list of Molly Application objects, e.g.,::

    APPLICATIONS = [
        Application('molly.apps.app1', 'app1', 'App 1',
            ... application config 1 ...
        ),
    
        Application('molly.apps.app2', 'app2', 'App 2',
            ... application config 2 ...
        ),
    
        Application('molly.apps.app3', 'app3', 'App 3',
            ... application config 3 ...
        ),
    ]

Details about configuration of each individual application are on the page for
that application, and more abstract information about the application framework
can be found at :doc:`../topics/application-framework`.

Applications bundled with Molly are split into two categories: utility, and
batteries-included. Utility apps must always be loaded, whereas
batteries-included apps represent optional user-facing functionality. However,
some batteries-included apps rely on others, so these must also be loaded.

The apps that are utility apps are:

* :doc:`../ref/auth`
* :doc:`../ref/batch-processing`
* :doc:`../ref/external-media`
* :doc:`../ref/favourites`
* :doc:`../ref/geolocation`
* :doc:`../ref/maps`
* :doc:`../ref/url-shortener`
* :doc:`../ref/utils`
* :doc:`../ref/wurfl`

The following battery-included apps are:

* :doc:`../ref/apps/contact`
* :doc:`../ref/apps/desktop`
* :doc:`../ref/apps/events`
* :doc:`../ref/apps/feature-vote`
* :doc:`../ref/apps/feedback`
* :doc:`../ref/apps/feeds` (required by news, events and webcams)
* :doc:`../ref/apps/home` (required)
* :doc:`../ref/apps/library`
* :doc:`../ref/apps/news`
* :doc:`../ref/apps/places` (required by library and transport)
* :doc:`../ref/apps/podcasts`
* :doc:`../ref/apps/sakai`
* :doc:`../ref/apps/search`
* :doc:`../ref/apps/service-status`
* :doc:`../ref/apps/tours`
* :doc:`../ref/apps/transport`
* :doc:`../ref/apps/weather`
* :doc:`../ref/apps/webcams`

API_KEYS
""""""""

This is a dictionary holding various API keys for your deployment. There is no
default for these, are you will need to get your own keys. The following two
keys are used: Cloudmade for geolocation and Google Analytics, if Google
Analytics is enabled. You can get a Cloudmade key from your
`user profile page on Cloudmade.com <http://cloudmade.com/user/show>`_, and
Google Analytics from the Analytics dashboard.

Sample::

    API_KEYS = {
        'cloudmade': 'MyCloudmadeKey',
        'google_analytics': 'MyGoogleAnalyticsKey',
    }

CACHE_DIR
"""""""""

CACHE_DIR_ should be set to a path where Molly can cache files (this includes
generated map tiles, resized images, etc), with no trailing slash.

Sample::

    CACHE_DIR = '/var/cache/molly' # This must be set, and there is no default

DEBUG_SECURE
""""""""""""

Whether or not secure parts of the site are in debug mode (this means less
rigorous checking of secure sessions and whether or https is required to access
parts of the site marked as secure).

Sample::

    DEBUG_SECURE = DEBUG # There is no default, but this would set it to the same value as the global DEBUG setting

DISTANCE_UNITS
""""""""""""""

This setting determines how distances are transformed into human-readable units.
The valid settings here are 'imperial', which uses yards and miles, 'metric'
which uses metres and kilometres, and 'british', which uses metres and miles.
This defaults to 'british'.

Sample::

    DISTANCE_UNITS = 'british'

EXTERNAL_IMAGES_DIR
"""""""""""""""""""

Where cached external images are stored, by default this is under the cache
directory, and is optional.

Sample::

    EXTERNAL_IMAGES_DIR = '/var/cache/molly-images'

IDENTIFIER_SCHEME_PREFERENCE
""""""""""""""""""""""""""""

Each entity has a primary identifier which is used to generate the absolute URL
of the entity page. We can define a list of identifier preferences, so that
when an entity is imported, these identifier namespaces are looked at in order
until a value in that namespace is chosen. This is then used as the primary
identifer. The default is shown in the sample below, and is optional::

    IDENTIFIER_SCHEME_PREFERENCE = ('atco', 'osm', 'naptan', 'postcode', 'bbc-tpeg')

MARKER_DIR
""""""""""

Where markers are stored, by default this is under the cache directory. This is
optional, but it may be useful to define it, as it needs to be referenced in the
STATICFILES_DIRS_ setting::

    MARKER_DIR = os.path.join(CACHE_DIR, 'markers')

NO_CACHE
""""""""

When set to true, then cache headers are suppressed from responses. This can be
used as a workaround to a `MOLLY-177 <http://issues.mollyproject.org/browse/MOLLY-177>`_.

SITE_NAME
"""""""""

The name of the service, extensively used in templates to name the service. This
defaults to 'Molly Project'::

    SITE_NAME = 'Mobile Oxford'