Pyramid supports a common form of virtual hosting whereby you
can host a Pyramid application as a “subset” of some other site
(e.g. under http://example.com/mypyramidapplication/ as opposed to
under http://example.com/).

If you use a “pure Python” environment, this functionality can be provided by
Paste’s urlmap “composite”
WSGI application. Alternately, you can use 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
Pyramid application or if you use mod_wsgi to serve
up a Pyramid application, nothing special needs to be done
within the application for URLs to be generated that contain a
prefix. paste.urlmap and mod_wsgi manipulate the
WSGI environment in such a way that the PATH_INFO and
SCRIPT_NAME variables are correct for some given prefix.

Here’s an example of a PasteDeploy configuration snippet that includes
a urlmap composite.

This “roots” the Pyramid application at the prefix
/pyramidapp and serves up the composite as the “main” application
in the file.

Note

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
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.

If you use mod_wsgi, you do not need to use a composite
application in your .ini file. The WSGIScriptAlias
configuration setting in a mod_wsgi configuration does the
work for you:

Pyramid also supports “virtual roots”, which can be used in
traversal -based (but not URL dispatch -based)
applications.

Virtual root support is useful when you’d like to host some resource in a
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 http://example.com/cms).

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 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
/cms subobject as http://www.example.com/ using this facility
is below: