"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 (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 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
SCRIPT_NAME variables are correct for some given prefix.
Here's an example of a PasteDeploy configuration snippet that includes a
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
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
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
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:
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
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