"Virtual hosting" is, loosely, the act of serving a Pyramid application or a portion of a Pyramid application under a URL space that it does not "naturally" inhabit.
Pyramid provides facilities for serving an application under a URL "prefix", as well as serving a portion of a traversal based application under a root URL.
Hosting an Application Under a URL Prefix¶
Pyramid supports a common form of virtual hosting whereby you
can host a 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 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
paste.urlmap and mod_wsgi manipulate the
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
1 2 3 4 5 6
[app:mypyramidapp] use = egg:mypyramidapp [composite:main] use = egg:Paste#urlmap /pyramidapp = mypyramidapp
This "roots" the 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.
WSGIScriptAlias /pyramidapp /Users/chrism/projects/modwsgi/env/pyramid.wsgi
In the above configuration, we root a 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
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
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
1 2 3 4 5 6 7 8 9
NameVirtualHost *:80 <VirtualHost *:80> ServerName www.example.com RewriteEngine On RewriteRule ^/(.*) http://127.0.0.1:6543/$1 [L,P] ProxyPreserveHost on RequestHeader add X-Vhm-Root /cms </VirtualHost>
Use of the
RequestHeader directive requires that the
Apache mod_headers module be
available in the Apache environment you're using.
For a Pyramid application running under mod_wsgi,
the same can be achieved using
1 2 3
<Location /> SetEnv HTTP_X_VHM_ROOT /cms </Location>
Setting a virtual root has no effect when using an application based on URL dispatch.
Further Documentation and Examples¶
The API documentation in pyramid.traversal documents a
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).