Virtual Hosting¶
"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
http://example.com/
).
If you use a "pure Python" environment, this functionality can be provided by rutter, forming a "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 rutter
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. Rutter 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
rutter
composite.
1[app:mypyramidapp]
2use = egg:mypyramidapp
3
4[composite:main]
5use = egg:rutter#urlmap
6/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 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:
1WSGIScriptAlias /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¶
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:
1NameVirtualHost *:80
2
3<VirtualHost *:80>
4 ServerName www.example.com
5 RewriteEngine On
6 RewriteRule ^/(.*) http://127.0.0.1:6543/$1 [L,P]
7 ProxyPreserveHost on
8 RequestHeader add X-Vhm-Root /cms
9</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 SetEnv
:
1<Location />
2 SetEnv HTTP_X_VHM_ROOT /cms
3</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).
Running a Pyramid Application under mod_wsgi has detailed information about using mod_wsgi to serve Pyramid applications.