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

  "Virtual Hosting" chapter.

1 files changed, 49 insertions, 0 deletions

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
 ----------------------------------