From 6ce1e0cf1a141767ee0aca70786c15dd993347c5 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Wed, 20 Jul 2011 06:10:38 -0400 Subject: add more index markers --- docs/narr/vhosting.rst | 3 +++ 1 file changed, 3 insertions(+) (limited to 'docs/narr/vhosting.rst') diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst index d3ff260e3..5679cc2e2 100644 --- a/docs/narr/vhosting.rst +++ b/docs/narr/vhosting.rst @@ -14,6 +14,9 @@ URL space that it does not "naturally" inhabit. a URL "prefix", as well as serving a *portion* of a :term:`traversal` based application under a root URL. +.. index:: + single: hosting an app under a prefix + Hosting an Application Under a URL Prefix ----------------------------------------- -- cgit v1.2.3 From fb90f0166728af40142ed9a31039d26ca3f97c73 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Sun, 14 Aug 2011 04:58:34 -0400 Subject: - The ``route_url``, ``route_path``, ``resource_url``, ``static_url``, and ``current_route_url`` functions in the ``pyramid.url`` package now delegate to a method on the request they've been passed, instead of the other way around. The pyramid.request.Request object now inherits from a mixin named pyramid.url.URLMethodsMixin to make this possible, and all url/path generation logic is embedded in this mixin. - Narrative and API documentation which used the ``route_url``, ``route_path``, ``resource_url``, ``static_url``, and ``current_route_url`` functions in the ``pyramid.url`` package have now been changed to use eponymous methods of the request instead. --- docs/narr/vhosting.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/vhosting.rst') diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst index 5679cc2e2..ddbf1fb4d 100644 --- a/docs/narr/vhosting.rst +++ b/docs/narr/vhosting.rst @@ -101,8 +101,8 @@ 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 :func:`pyramid.url.resource_url` API will generate the -"correct" virtually-rooted URLs. +starts), and the :meth:`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 -- cgit v1.2.3 From 3d338ea5737b7c113b17120b40684e2694cf3fa9 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Mon, 22 Aug 2011 02:16:55 -0400 Subject: - Use [app:main] instead of a pipeline in all scaffolds and tutorials and narrative docs. - Break out awkward description of PasteDeploy entry points from project chapter into its own Paste chapter. --- docs/narr/vhosting.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/narr/vhosting.rst') diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst index ddbf1fb4d..8697df6a0 100644 --- a/docs/narr/vhosting.rst +++ b/docs/narr/vhosting.rst @@ -46,7 +46,7 @@ a ``urlmap`` composite. :linenos: [app:mypyramidapp] - use = egg:mypyramidapp#app + use = egg:mypyramidapp [composite:main] use = egg:Paste#urlmap -- cgit v1.2.3 From 09387f5cb04eb08b18c24a41248af0a13648286e Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 1 Sep 2011 22:15:08 -0400 Subject: - Added a "Fixing HTTP vs. HTTP When Deploying Behind a Proxy" section to the "Virtual Hosting" chapter. --- docs/narr/vhosting.rst | 49 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 49 insertions(+) (limited to 'docs/narr/vhosting.rst') diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst index 8697df6a0..086af78f7 100644 --- a/docs/narr/vhosting.rst +++ b/docs/narr/vhosting.rst @@ -139,6 +139,55 @@ the same can be achieved using ``SetEnv``: Setting a virtual root has no effect when using an application based on :term:`URL dispatch`. +Fixing HTTP vs. HTTPS When Deploying Behind a Proxy +--------------------------------------------------- + +In a configuration where you have a :app:`Pyramid` server behind an Apache or +Nginx or Squid proxy which serves your website over SSL (as ``https``) as in +the above example in :ref:`virtual_root_support`, the request will be passed +by the proxy to an `http://`` URL that will be served by :app:`Pyramid`. +Because this is true, URLs generated by :app:`Pyramid` will be generated with +``http://`` instead of ``https://``; the SSL info has been "lost" during the +proxying. + +To work around this, convert your application to use a "pipeline" instead of +a simple "app" in your PasteDeploy configuration, then add ``prefix`` +middleware to the pipeline. For example, if your ``production.ini`` file has +a ``main`` section that looks like this: + +.. code-block:: ini + + [app:main] + use = egg:MyProject + +Convert it to look like this: + +.. code-block:: ini + + [app:myapp] + use = egg:MyProject + + [pipeline:main] + pipeline = + myapp + +Then add the ``paste.prefix`` middleware with no options to the pipeline: + +.. code-block:: ini + + [app:myapp] + use = egg:MyProject + + [filter:paste_prefix] + use = egg:PasteDeploy#prefix + + [pipeline:main] + pipeline = + paste_prefix + myapp + +This will have the side effect of retaining ``https`` URLs during generation. + Further Documentation and Examples ---------------------------------- -- cgit v1.2.3 From 7c1549608daf2e3a6965320b1ef8362d8b4dd618 Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Fri, 2 Sep 2011 00:23:23 -0400 Subject: remove; too complex to document here --- docs/narr/vhosting.rst | 49 ------------------------------------------------- 1 file changed, 49 deletions(-) (limited to 'docs/narr/vhosting.rst') diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst index 086af78f7..8697df6a0 100644 --- a/docs/narr/vhosting.rst +++ b/docs/narr/vhosting.rst @@ -139,55 +139,6 @@ the same can be achieved using ``SetEnv``: Setting a virtual root has no effect when using an application based on :term:`URL dispatch`. -Fixing HTTP vs. HTTPS When Deploying Behind a Proxy ---------------------------------------------------- - -In a configuration where you have a :app:`Pyramid` server behind an Apache or -Nginx or Squid proxy which serves your website over SSL (as ``https``) as in -the above example in :ref:`virtual_root_support`, the request will be passed -by the proxy to an `http://`` URL that will be served by :app:`Pyramid`. -Because this is true, URLs generated by :app:`Pyramid` will be generated with -``http://`` instead of ``https://``; the SSL info has been "lost" during the -proxying. - -To work around this, convert your application to use a "pipeline" instead of -a simple "app" in your PasteDeploy configuration, then add ``prefix`` -middleware to the pipeline. For example, if your ``production.ini`` file has -a ``main`` section that looks like this: - -.. code-block:: ini - - [app:main] - use = egg:MyProject - -Convert it to look like this: - -.. code-block:: ini - - [app:myapp] - use = egg:MyProject - - [pipeline:main] - pipeline = - myapp - -Then add the ``paste.prefix`` middleware with no options to the pipeline: - -.. code-block:: ini - - [app:myapp] - use = egg:MyProject - - [filter:paste_prefix] - use = egg:PasteDeploy#prefix - - [pipeline:main] - pipeline = - paste_prefix - myapp - -This will have the side effect of retaining ``https`` URLs during generation. - Further Documentation and Examples ---------------------------------- -- cgit v1.2.3 From f8869cb0664506204b22aa791003a6d5f8ded58c Mon Sep 17 00:00:00 2001 From: Chris McDonough Date: Thu, 6 Oct 2011 03:22:35 -0400 Subject: remove stray references to Paste --- docs/narr/vhosting.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) (limited to 'docs/narr/vhosting.rst') diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst index 8697df6a0..d37518052 100644 --- a/docs/narr/vhosting.rst +++ b/docs/narr/vhosting.rst @@ -25,11 +25,11 @@ can host a :app:`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 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 a "pure Python" environment, this functionality can be 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 :app:`Pyramid` application or if you use :term:`mod_wsgi` to serve -- cgit v1.2.3 From 392a6c7df93b67d6889680133fda0f744970d61f Mon Sep 17 00:00:00 2001 From: Antti Haapala Date: Sun, 17 Nov 2013 00:11:37 +0200 Subject: Removed extra indentation from some examples (:linenos: should be indented with the same indentation as the rest of the code block) --- docs/narr/vhosting.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'docs/narr/vhosting.rst') diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst index d37518052..53f6888b3 100644 --- a/docs/narr/vhosting.rst +++ b/docs/narr/vhosting.rst @@ -109,7 +109,7 @@ An example of an Apache ``mod_proxy`` configuration that will host the is below: .. code-block:: apache - :linenos: + :linenos: NameVirtualHost *:80 @@ -130,7 +130,7 @@ For a :app:`Pyramid` application running under :term:`mod_wsgi`, the same can be achieved using ``SetEnv``: .. code-block:: apache - :linenos: + :linenos: SetEnv HTTP_X_VHM_ROOT /cms -- cgit v1.2.3 From df04cbcc7e4e3f9d73eb1bb213f786554d000740 Mon Sep 17 00:00:00 2001 From: Steve Piercy Date: Tue, 20 Oct 2015 02:05:02 -0700 Subject: minor grammar, rewrap 79 columns --- docs/narr/vhosting.rst | 117 +++++++++++++++++++++++-------------------------- 1 file changed, 55 insertions(+), 62 deletions(-) (limited to 'docs/narr/vhosting.rst') diff --git a/docs/narr/vhosting.rst b/docs/narr/vhosting.rst index 53f6888b3..0edf03353 100644 --- a/docs/narr/vhosting.rst +++ b/docs/narr/vhosting.rst @@ -6,13 +6,13 @@ Virtual Hosting =============== -"Virtual hosting" is, loosely, the act of serving a :app:`Pyramid` -application or a portion of a :app:`Pyramid` application under a -URL space that it does not "naturally" inhabit. +"Virtual hosting" is, loosely, the act of serving a :app:`Pyramid` application +or a portion of a :app:`Pyramid` application under a URL space that it does not +"naturally" inhabit. -:app:`Pyramid` provides facilities for serving an application under -a URL "prefix", as well as serving a *portion* of a :term:`traversal` -based application under a root URL. +:app:`Pyramid` provides facilities for serving an application under a URL +"prefix", as well as serving a *portion* of a :term:`traversal` based +application under a root URL. .. index:: single: hosting an app under a prefix @@ -20,27 +20,26 @@ based application under a root URL. Hosting an Application Under a URL Prefix ----------------------------------------- -:app:`Pyramid` supports a common form of virtual hosting whereby you -can host a :app:`Pyramid` application as a "subset" of some other site -(e.g. under ``http://example.com/mypyramidapplication/`` as opposed to -under ``http://example.com/``). +:app:`Pyramid` supports a common form of virtual hosting whereby you can host a +:app:`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 :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 -:app:`Pyramid` application or if you use :term:`mod_wsgi` to serve -up a :app:`Pyramid` application, nothing special needs to be done -within the application for URLs to be generated that contain a -prefix. :mod:`paste.urlmap` and :term:`mod_wsgi` manipulate the -:term:`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. +Paste's `urlmap `_ "composite" WSGI +application. Alternatively, 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 :app:`Pyramid` +application or if you use :term:`mod_wsgi` to serve up a :app:`Pyramid` +application, nothing special needs to be done within the application for URLs +to be generated that contain a prefix. :mod:`paste.urlmap` and :term:`mod_wsgi` +manipulate the :term:`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. .. code-block:: ini :linenos: @@ -52,23 +51,21 @@ a ``urlmap`` composite. use = egg:Paste#urlmap /pyramidapp = mypyramidapp -This "roots" the :app:`Pyramid` application at the prefix -``/pyramidapp`` and serves up the composite as the "main" application -in the file. +This "roots" the :app:`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 +.. 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. + 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 :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: +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: @@ -87,8 +84,7 @@ Virtual Root Support -------------------- :app:`Pyramid` also supports "virtual roots", which can be used in -:term:`traversal` -based (but not :term:`URL dispatch` -based) -applications. +:term:`traversal`-based (but not :term:`URL dispatch`-based) applications. Virtual root support is useful when you'd like to host some resource in a :app:`Pyramid` resource tree as an application under a URL pathname that does @@ -98,15 +94,14 @@ object at the traversal path ``/cms`` as an application reachable via 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 :meth:`pyramid.request.Request.resource_url` API will -generate the "correct" virtually-rooted URLs. +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 :meth:`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: +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:: apache :linenos: @@ -121,13 +116,12 @@ 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. +.. note:: Use of the ``RequestHeader`` directive requires that the Apache + `mod_headers `_ + module be available in the Apache environment you're using. -For a :app:`Pyramid` application running under :term:`mod_wsgi`, -the same can be achieved using ``SetEnv``: +For a :app:`Pyramid` application running under :term:`mod_wsgi`, the same can +be achieved using ``SetEnv``: .. code-block:: apache :linenos: @@ -136,17 +130,16 @@ the same can be achieved using ``SetEnv``: SetEnv HTTP_X_VHM_ROOT /cms -Setting a virtual root has no effect when using an application based -on :term:`URL dispatch`. +Setting a virtual root has no effect when using an application based on +:term:`URL dispatch`. Further Documentation and Examples ---------------------------------- The API documentation in :ref:`traversal_module` documents a -:func:`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). - -:ref:`modwsgi_tutorial` has detailed information about using -:term:`mod_wsgi` to serve :app:`Pyramid` applications. +:func:`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). +:ref:`modwsgi_tutorial` has detailed information about using :term:`mod_wsgi` +to serve :app:`Pyramid` applications. -- cgit v1.2.3