From 524bfe38c52493dec96164345dd3130536e92372 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 11 Oct 2009 02:04:51 +0000 Subject: Include vhosting info for modwsgi. --- docs/narr/project.rst | 3 ++- docs/narr/vhosting.rst | 56 +++++++++++++++++++++++++++++++++++++------------- 2 files changed, 44 insertions(+), 15 deletions(-) diff --git a/docs/narr/project.rst b/docs/narr/project.rst index 43628d2e8..f178b854f 100644 --- a/docs/narr/project.rst +++ b/docs/narr/project.rst @@ -183,7 +183,8 @@ file which points to your *application* as opposed to any other section within the ``.ini`` file. For example, if your application ``.ini`` file might have a ``[app:main]`` section that looks like so: -.. code-block: +.. code-block:: ini + :linenos: [app:main] use = egg:MyProject#app diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst index 4546446be..7394f2173 100644 --- a/docs/narr/vhosting.rst +++ b/docs/narr/vhosting.rst @@ -7,18 +7,23 @@ Hosting an Application Under a URL Prefix ----------------------------------------- :mod:`repoze.bfg` supports a traditional form of virtual hosting -provided by packages like Paste's `urlmap -`_ "composite" WSGI -application. Using such a package, you can host a :mod:`repoze.bfg` -application as a "subset" of some other site -(e.g. ``http://example.com/mybfgapplication/``). +whereby you can host a :mod:`repoze.bfg` application as a "subset" of +some other site (e.g. under ``http://example.com/mybfgapplication/`` +as opposed to under ``http://example.com/``). + +If you use a "pure Python" environment, this functionality is provided +by Paste's `urlmap `_ +"composite" WSGI application. Alternately, 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 -:mod:`repoze.bfg` application, nothing special needs to be done within -the application for URLs to be generated that contain the prefix -spelled by the package config. Packages such as ``urlmap`` manipulate -the WSGI environment in such a way that the ``PATH_INFO`` and -``SCRIPT_NAME`` variables are correct for some given prefix. +:mod:`repoze.bfg` application or if you use :term:`mod_wsgi` to serve +up a :mod:`repoze.bfg` application, nothing special needs to be done +within the application for URLs to be generated that contain the +prefix spelled by the package config. ``urlmap`` and ``mod_wsgi`` and +manipulate the WSGI environment in such a way that the ``PATH_INFO`` +and ``SCRIPT_NAME`` variables are correct for some given prefix. .. note:: If you're using an Apache server to proxy to a Paste ``urlmap`` composite, you may have to use the `ProxyPreserveHost @@ -45,6 +50,18 @@ This "roots" the :mod:`repoze.bfg` application at the prefix ``/bfgapp`` and serves up the composite as the "main" application in the file. +If you use :term:`mod_wsgi`, you do not need to use a ``composite`` +application in your .ini file. The ``WSGIScriptAlias`` configuration +setting in a :term:`mod_wsgi` configuration does the work for you: + +.. code-block:: apache + :linenos: + + WSGIScriptAlias /bfgapp /Users/chrism/projects/modwsgi/env/bfg.wsgi + +In the above configuration, we root a :mod:`repoze.bfg` application at +``/bfgapp`` within the Apache configuration. + Virtual Root Support -------------------- @@ -72,7 +89,8 @@ An example of an Apache ``mod_proxy`` configuration that will host the ``/cms`` subobject as ``http://www.example.com/`` using this facility is below: -.. code-block:: xml +.. code-block:: apache + :linenos: NameVirtualHost *:80 @@ -84,14 +102,20 @@ is below: RequestHeader add X-Vhm-Root /cms +.. note:: Use of the ``RequestHeader`` directive requires that the + Apache `mod_headers + `_ module be + available in the Apache environment you're using. + For a :mod:`repoze.bfg` application running under ``mod_wsgi``, the same can be achieved using ``SetEnv``: -.. code-block:: xml +.. code-block:: apache + :linenos: - SetEnv HTTP_X_VHM_ROOT /cms - + SetEnv HTTP_X_VHM_ROOT /cms + Setting a virtual root has no effect when using an application based on :term:`URL dispatch`. @@ -103,3 +127,7 @@ The API documentation in :ref:`traversal_module` documents a ``repoze.bfg.traversal.virtual_root`` API. When called, it returns the virtual root object (or the physical root object if no virtual root has been specified). + +:ref:`modwsgi_tutorial` has detailed information about using +:term:`mod_wsgi` to serve :mod:`repoze.bfg` applications. + -- cgit v1.2.3