Skip to main content
Help us improve Python packaging – donate today!

Serve multiple sites from a single Django application

Project Description

.. image:: https://travis-ci.org/ecometrica/django-multisite.svg?branch=master
:target: https://travis-ci.org/ecometrica/django-multisite?branch=master
.. image:: https://coveralls.io/repos/github/ecometrica/django-multisite/badge.svg?branch=master
:target: https://coveralls.io/github/ecometrica/django-multisite?branch=master


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

.. _cross-domain cookies: http://en.wikipedia.org/wiki/HTTP_cookie#Domain_and_Path
.. _Public Suffix List: http://publicsuffix.org/


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.

Release history Release notifications

This version
History Node

1.4.1

History Node

1.4.0

History Node

1.3.1

History Node

1.3.0

History Node

1.2.6

History Node

1.2.5

History Node

1.2.4

History Node

1.2.3

History Node

1.2.2

History Node

1.2.1

History Node

1.2.0

History Node

1.1.2

History Node

1.1.1

History Node

1.1.0

History Node

1.0.0

History Node

0.5.1

History Node

0.5.0

History Node

0.4.1

History Node

0.4.0

History Node

0.3.1

History Node

0.3.0

History Node

0.2.4

History Node

0.2.3

History Node

0.2.2

History Node

0.2.1

History Node

0.2

History Node

0.1

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Filename, size & hash SHA256 hash help File type Python version Upload date
django-multisite-1.4.1.tar.gz (26.9 kB) Copy SHA256 hash SHA256 Source None Dec 22, 2017

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging CloudAMQP CloudAMQP RabbitMQ AWS AWS Cloud computing Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page