Hosting an Application Under a URL Prefix
:app:`Pyramid` supports a common form of virtual hosting whereby you
can host a :app:`Pyramid` application as a "subset" of some other site
http://example.com/mypyramidapplication/ as opposed to
If you use a "pure Python" environment, this functionality is provided by Paste's urlmap "composite" WSGI application. Alternately, you can use :term:`mod_wsgi` to serve your application, which handles this virtual hosting translation for you "under the hood".
If you use the
urlmap composite application "in front" of a
:app:`Pyramid` application or if you use :term:`mod_wsgi` to serve
up a :app:`Pyramid` application, nothing special needs to be done
within the application for URLs to be generated that contain a
prefix. :mod:`paste.urlmap` and :term:`mod_wsgi` manipulate the
:term:`WSGI` environment in such a way that the
SCRIPT_NAME variables are correct for some given prefix.
Here's an example of a PasteDeploy configuration snippet that includes
This "roots" the :app:`Pyramid` application at the prefix
/pyramidapp and serves up the composite as the "main" application
in the file.
If you're using an Apache server to proxy to a Paste
urlmap composite, you may have to use the ProxyPreserveHost
directive to pass the original
HTTP_HOST header along to the
application, so URLs get generated properly. As of this writing
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.
In the above configuration, we root a :app:`Pyramid` application at
/pyramidapp within the Apache configuration.
Virtual Root Support
Virtual root support is useful when you'd like to host some model in a
:app:`Pyramid` object graph as an application under a URL pathname
that does not include the model path itself. For example, you might
want to serve the object at the traversal path
/cms as an
application reachable via
http://example.com/ (as opposed to
To specify a virtual root, cause an environment variable to be
inserted into the WSGI environ named
HTTP_X_VHM_ROOT with a value
that is the absolute pathname to the model object in the traversal
graph that should behave as the "root" model. As a result, the
traversal machinery will respect this value during traversal
(prepending it to the PATH_INFO before traversal starts), and the
:func:`pyramid.url.model_url` API will generate the "correct"
An example of an Apache
mod_proxy configuration that will host the
/cms subobject as
http://www.example.com/ using this facility
Use of the
RequestHeader directive requires that the
Apache mod_headers module be
available in the Apache environment you're using.
Setting a virtual root has no effect when using an application based on :term:`URL dispatch`.
Further Documentation and Examples
The API documentation in :ref:`traversal_module` documents a :func:`pyramid.traversal.virtual_root` API. When called, it returns the virtual root object (or the physical root object if no virtual root has been specified).