From 0c29f02fd44314f454f7eb051ccfb7ff0933c97c Mon Sep 17 00:00:00 2001
From: Michael Merickel <michael@merickel.org>
Date: Tue, 14 Jul 2020 22:32:34 -0500
Subject: add a dedicated section for handling heroku

---
 docs/usage.rst | 32 +++++++++++++++++---------------
 1 file changed, 17 insertions(+), 15 deletions(-)

diff --git a/docs/usage.rst b/docs/usage.rst
index 872c045..dfcd6dc 100644
--- a/docs/usage.rst
+++ b/docs/usage.rst
@@ -80,23 +80,25 @@ can be used in development and in situations where the likes of
     # Listen on only IPv4 on port 8041
     waitress-serve --port=8041 myapp:wsgifunc
 
-Waitress can be used to serve WSGI apps on Heroku, include waitress in your
-requirements.txt file a update the Procfile as following:
+Heroku
+------
+
+Waitress can be used to serve WSGI apps on Heroku, include waitress in your requirements.txt file a update the Procfile as following:
 
 .. code-block:: bash
 
-    web: waitress-serve \
-  --listen "*:$PORT" \
-  --trusted-proxy '*' \
-  --trusted-proxy-headers 'x-forwarded-for x-forwarded-proto x-forwarded-port' \
-  --log-untrusted-proxy-headers \
-  --clear-untrusted-proxy-headers \
-  --threads ${WEB_CONCURRENCY:-4} \
-  myapp:wsgifunc
-
-Note that Waitress uses a thread-based model and careful effort should be taken to ensure
-that requests do not take longer than 30 seconds or Heroku will inform the client that the
-request failed even though the request is still being processed by waitress and occupying
-a thread until it completes.
+   web: waitress-serve \
+       --listen "*:$PORT" \
+       --trusted-proxy '*' \
+       --trusted-proxy-headers 'x-forwarded-for x-forwarded-proto x-forwarded-port' \
+       --log-untrusted-proxy-headers \
+       --clear-untrusted-proxy-headers \
+       --threads ${WEB_CONCURRENCY:-4} \
+       myapp:wsgifunc
+
+The proxy config informs Waitress to trust the `forwarding headers <https://devcenter.heroku.com/articles/http-routing#heroku-headers>`_ set by the Heroku load balancer.
+It also allows for setting the standard ``WEB_CONCURRENCY`` environment variable to tweak the number of requests handled by Waitress at a time.
+
+Note that Waitress uses a thread-based model and careful effort should be taken to ensure that requests do not take longer than 30 seconds or Heroku will inform the client that the request failed even though the request is still being processed by Waitress and occupying a thread until it completes.
 
 For more information on this, see :ref:`runner`.
-- 
cgit v1.2.1