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, 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 by default the people defined here will receive logging e-mails and cronjob output
  • ADMIN_MEDIA_PREFIX
  • 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
  • LANGUAGE_CODE
  • 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 - this is where Molly will find any translation files you have prepared
  • MANAGERS Molly gives this setting no special meaning, so it is recommended you set this to the same as ADMINS
  • SITE_ID unused in most situations, so leave at 1
  • 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 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 Deploying Molly).
  • TEMPLATE_DEBUG
  • 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

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

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

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

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

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

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

Like MIDDLEWARE_CLASSES, this can vary between installations, but the Django reference 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). 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

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

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

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

In order to deliver minified CSS and JavaScript, Molly uses a fork of 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

New in version 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.

Remaining options are best explained in the Celery documentation.

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 The 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:

The following battery-included apps are:

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, 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.

SITE_NAME

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

SITE_NAME = 'Mobile Oxford'