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 (e.g., under
http://example.com/mypyramidapplication/ as opposed to under
If you use a "pure Python" environment, this functionality can be provided by Paste's urlmap "composite" WSGI application. Alternatively, 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 a
This "roots" the :app:`Pyramid` application at the prefix
serves up the composite as the "main" application in the file.
If you're using an Apache server to proxy to a Paste
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 the
urlmap composite does not seem to respect the
parameter, which will contain the original host header even if
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 resource in a
:app:`Pyramid` resource tree as an application under a URL pathname that does
not include the resource 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 resource object in the resource tree that should behave as the
"root" resource. As a result, the traversal machinery will respect this value
during traversal (prepending it to the PATH_INFO before traversal starts), and
the :meth:`pyramid.request.Request.resource_url` API will generate the
"correct" virtually-rooted URLs.
An example of an Apache
mod_proxy configuration that will host the
http://www.example.com/ using this facility is below:
Use of the
RequestHeader directive requires that the Apache
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).