- Added a "Fixing HTTP vs. HTTP When Deploying Behind a Proxy" section to the

  "Virtual Hosting" chapter.

3 files changed, 55 insertions, 7 deletions

diff --git a/CHANGES.txt b/CHANGES.txt
index 873c445e9..42ef1ae90 100644
--- a/CHANGES.txt
+++ b/CHANGES.txt
@@ -31,6 +31,12 @@ Dependencies
 - Pyramid now requires Venusian 1.0a1 or better to support the ``onerror``
   keyword argument to ``pyramid.config.Configurator.scan``.
 
+Documentation
+-------------
+
+- Added a "Fixing HTTP vs. HTTP When Deploying Behind a Proxy" section to the
+  "Virtual Hosting" chapter.
+
 1.2a3 (2011-08-29)
 ==================
 
diff --git a/TODO.txt b/TODO.txt
index 95bd2b917..7fcd7ff1c 100644
--- a/TODO.txt
+++ b/TODO.txt
@@ -1,13 +1,6 @@
 Pyramid TODOs
 =============
 
-Should-Have
------------
-
-- Example of using paste prefix middleware to fix https-vs-http when
-  deploying via proxy:
-  https://docs.pylonsproject.org/projects/pyramid_cookbook/dev/deployment/nginx.html#step-2-starting-paster
-
 Nice-to-Have
 ------------
 
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
 ----------------------------------