- Added better documentation for virtual hosting at a URL prefix

  within the virtual hosting docs chapter.

2 files changed, 46 insertions, 9 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 3a6006c07..2551c3c17 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -4,6 +4,9 @@ Next release
 Features
 --------
 
+- Added better documentation for virtual hosting at a URL prefix
+  within the virtual hosting docs chapter.
+
 - The interface for ``repoze.bfg.interfaces.ITraverser`` and the
   built-in implementations that implement the interface
   (``repoze.bfg.traversal.ModelGraphTraverser``, and
diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst
index 35bd046e7..d253d982a 100644
--- a/docs/narr/vhosting.rst
+++ b/docs/narr/vhosting.rst
@@ -3,21 +3,55 @@
 Virtual Hosting
 ===============
 
+Hosting an Application Under a URL Prefix
+-----------------------------------------
+
 :mod:`repoze.bfg` supports a traditional form of virtual hosting
 provided by packages like Paste's `urlmap
-<http://pythonpaste.org/modules/urlmap.html>`_ middleware, where you
-can host a :mod:`repoze.bfg` application as a "subset" of some other
-site (e.g. ``http://example.com/mybfgapplication``).  Nothing special
-needs to be done within a :mod:`repoze.bfg` application to make this
-work.
-
-However, :mod:`repoze.bfg` also supports "virtual roots", which can be
-used in :term:`traversal` -based (but not :term:`URL dispatch` -based)
-applications.  These are explained below.
+<http://pythonpaste.org/modules/urlmap.html>`_ "composite" WSGI
+application.  Using such a package, you can host a :mod:`repoze.bfg`
+application as a "subset" of some other site
+(e.g. ``http://example.com/mybfgapplication/``).
+
+If you use the ``urlmap`` composite application "in front" of a
+:mod:`repoze.bfg` application, nothing special needs to be done within
+the application for URLs to be generated that contain the prefix
+spelled by the package config.  Packages such as ``urlmap`` manipulate
+the WSGI environment in such a way that the ``PATH_INFO`` and
+``SCRIPT_NAME`` variables are correct for some given prefix.
+
+.. note:: If you're using an Apache server to proxy to a Paste
+   ``urlmap`` composite, you may have to use the `ProxyPreserveHost
+   <http://httpd.apache.org/docs/2.2/mod/mod_proxy.html#proxypreservehost>`_
+   directive to pass the original ``HTTP_HOST`` header along to the
+   application, so URLs get generated properly.  As of this writing
+   the ``urlmap`` composite does not seem to respect the
+   ``HTTP_X_FORWARDED_HOST`` parameter, which will contain the
+   original host header even if ``HTTP_HOST`` is incorrect.
+
+Here's an example of a PasteDeploy configuration snippet that includes
+a ``urlmap`` composite.
+
+.. code-block:: ini
+
+  [app:mybfgapp]
+  use = egg:mybfgapp#app
+
+  [composite:main]
+  use = egg:Paste#urlmap
+  /bfgapp =  bfgapp
+
+This "roots" the :mod:`repoze.bfg` application at the prefix
+``/bfgapp`` and serves up the composite as the "main" application in
+the file.
 
 Virtual Root Support
 --------------------
 
+:mod:`repoze.bfg` also supports "virtual roots", which can be used in
+:term:`traversal` -based (but not :term:`URL dispatch` -based)
+applications.  These are explained below.
+
 Virtual root support is useful when you'd like to host some model in a
 :mod:`repoze.bfg` model graph as an application under a URL pathname
 that does not include the model path itself.  For example, you might