From 09387f5cb04eb08b18c24a41248af0a13648286e Mon Sep 17 00:00:00 2001
From: Chris McDonough <chrism@plope.com>
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')

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