django-multihost 0.3
Simple multihost handling for Django
License: BSD

Django-Multihost -- A simplified, flexible Django multi-host app
================================================================


Overview
--------

Django-Multihost is a Django middleware that overrides Site ORM functionality and gets the current Site from the Host header.  The code is loosely based on the work done by Bruce Kroeze here: `django-threaded-multihost <http://bitbucket.org/bkroeze/django-threaded-multihost/>`_.


Description
-----------

The MultiHostMiddleware class contained in this app has 2 tasks:

#.  Upon middleware __init__(), it overrides SiteManager.get_current() with a multihost-aware version that reads the ``Host`` header from the request and attempts to find a matching Site (caches it if cache is enabled).
#.  Upon middleware process_request(), it sets the request into ``threadlocal`` storage and then uses the new SiteManager.get_current() functionality to retrieve the Site matching the ``Host`` header and sets it into the request instance.  If a match is not found and MULTIHOST_AUTO_WWW is True (the default), it will attempt to modify the ``Host`` URL  to add/remove ``www.`` and attempt the lookup again.  If it still doesn't find a matching Site, it redirects to ``MULTIHOST_REDIRECT_URL``.


Requirements
------------

- Python 2.6 (May work with 2.3+, but untested - please report)
- Django 1.2.x (May work with 1.0+, but untested - please report)


Installation
------------

#. Copy or symlink the ``multihost`` package into your django project directory or install it by running one of the following commands:

    ``python setup.py install``

    or

    ``pip install django-multihost``
    
    or

    ``easy_install django-multihost``

#. Add ``MULTIHOST_REDIRECT_URL`` to ``settings.py``

#. Add ``multihost.middleware.MultiHostMiddleware`` to your ``MIDDLEWARE_CLASSES`` in at the end of the list.  If you find it isn't working, move it up the list order as there may be a middleware conflict.

Note: Django does strange things (like sending requests to the wrong urls handler) when it is used in conjunction with debug_toolbar.  To fix this problem, multihost must always be the last entry in MIDDLEWARE_CLASSES.

Advanced Settings
----------------------

There are 2 settings that developers can use to override default functionality:

- ``MULTIHOST_REDIRECT_URL``: **required**; no default.  The default middleware request processing will redirect to this URL in the case of Site lookup failure.
- ``MULTIHOST_AUTO_WWW``: optional; defaults to True.  If the Site can't be found that matches the incoming Host header exactly, this will automatically try removing/adding ``www.`` and searching again.


Notes
-----

It is important to note that the MultiHostMiddleware middleware does database lookups against the Django tables corresponding to the `Site` model - in particular, against the `domain` field.  In the default Django implementation (version 1.2.1 as of writing), the `domain` field is not indexed or unique and this may result in slower performance over time.

For this reason, web site/application developers should weigh the benefits and consider manually adding an index for the `Site` model's `domain` field using standard database access tools.


Source
------

The latest source code can always be found here: `github.com/jaddison/django-multihost <http://github.com/jaddison/django-multihost/>`_


Credits
-------

Django-Multihost is maintained by `James Addison <mailto:code@scottisheyes.com>`_.


License
-------

Django-Multihost is Copyright (c) 2010-2012, James Addison. It is free software, and may be redistributed under the terms specified in the LICENSE file. 


Questions, Comments, Concerns:
------------------------------

Feel free to open an issue here: `github.com/jaddison/django-multihost/issues <http://github.com/jaddison/django-multihost/issues/>`_