README

Install with pip:

pip install django-multisite

Or get the code via git:

git clone git://github.com/ecometrica/django-multisite.git django-multisite

Then run:

python setup.py install

Or add the django-multisite/multisite folder to your PYTHONPATH.

If you wish to contribute, instead run:

python setup.py develop

Quickstart

Replace your SITE_ID in settings.py to:

from multisite import SiteID
SITE_ID = SiteID(default=1)

Add these to your INSTALLED_APPS:

INSTALLED_APPS = [
    ...
    'django.contrib.sites',
    'multisite',
    ...
]

Add to your settings.py TEMPLATES loaders in the OPTIONS section:

TEMPLATES = [
    ...
    {
        ...
        'DIRS': {...}
        'OPTIONS': {
            'loaders': (
                'multisite.template.loaders.filesystem.Loader',
                'django.template.loaders.app_directories.Loader',
            )
        }
        ...
    }
    ...
]

Or for Django 1.7 and earlier, add to settings.py TEMPLATES_LOADERS:

TEMPLATE_LOADERS = (
    'multisite.template.loaders.filesystem.Loader',
    'django.template.loaders.app_directories.Loader',
)

Edit settings.py MIDDLEWARE_CLASSES:

MIDDLEWARE_CLASSES = (
    ...
    'multisite.middleware.DynamicSiteMiddleware',
    ...
)

Append to settings.py, in order to use a custom cache that can be safely cleared:

# The cache connection to use for django-multisite.
# Default: 'default'
CACHE_MULTISITE_ALIAS = 'multisite'

# The cache key prefix that django-multisite should use.
# If not set, defaults to the KEY_PREFIX used in the defined
# CACHE_MULTISITE_ALIAS or the default cache (empty string if not set)
CACHE_MULTISITE_KEY_PREFIX = ''

If you have set CACHE_MULTISITE_ALIAS to a custom value, e.g. 'multisite', add a separate backend to settings.py CACHES:

CACHES = {
    'default': {
        ...
    },
    'multisite': {
        'BACKEND': 'django.core.cache.backends.locmem.LocMemCache',
        'TIMEOUT': 60 * 60 * 24,  # 24 hours
        ...
    },
}

Multisite determines the ALLOWED_HOSTS by checking all Alias domains. You can also set the MULTISITE_EXTRA_HOSTS to include additional hosts. This can include wildcards.:

MULTISITE_EXTRA_HOSTS = ['example.com']
# will match the single additional host

MULTISITE_EXTRA_HOSTS = ['.example.com']
# will match any host ending '.example.com'

Domain fallbacks

By default, if the domain name is unknown, multisite will respond with an HTTP 404 Not Found error. To change this behaviour, add to settings.py:

# The view function or class-based view that django-multisite will
# use when it cannot match the hostname with a Site. This can be
# the name of the function or the function itself.
# Default: None
MULTISITE_FALLBACK = 'django.views.generic.base.RedirectView

# Keyword arguments for the MULTISITE_FALLBACK view.
# Default: {}
MULTISITE_FALLBACK_KWARGS = {'url': 'http://example.com/',
                             'permanent': False}

Templates

If required, create template subdirectories for domain level templates (in a location specified in settings.TEMPLATES['DIRS'], or in settings.TEMPLATE_DIRS for Django <=1.7).

Multisite's template loader will look for templates in folders with the names of domains, such as:

templates/example.com

The template loader will also look for templates in a folder specified by the optional MULTISITE_DEFAULT_TEMPLATE_DIR setting, e.g.:

templates/multisite_templates

Cross-domain cookies

In order to support cross-domain cookies, for purposes like single-sign-on, prepend the following to the top of settings.py MIDDLEWARE_CLASSES:

MIDDLEWARE_CLASSES = (
    'multisite.middleware.CookieDomainMiddleware',
    ...
)

CookieDomainMiddleware will consult the Public Suffix List for effective top-level domains. It caches this file in the system's default temporary directory as effective_tld_names.dat. To change this in settings.py:

MULTISITE_PUBLIC_SUFFIX_LIST_CACHE = '/path/to/multisite_tld.dat'

By default, any cookies without a domain set will be reset to allow *.domain.tld. To change this in settings.py:

MULTISITE_COOKIE_DOMAIN_DEPTH = 1  # Allow only *.subdomain.domain.tld

In order to fetch a new version of the list, run:

manage.py update_public_suffix_list

Tests

To run the tests:

python setup.py test

Or:

pytest

Before deploying a change, to verify it has not broken anything by running:

tox

This runs the tests under every supported combination of Django and Python.