diff --git a/doc/source/apache-httpd.rst b/doc/source/apache-httpd.rst
index dbebc86e80..1436ddadfa 100644
--- a/doc/source/apache-httpd.rst
+++ b/doc/source/apache-httpd.rst
@@ -19,17 +19,73 @@
Running Keystone in HTTPD
=========================
+mod_proxy_uwsgi
+---------------
+
+The recommended keystone deployment is to have a real web server such as Apache
+HTTPD or nginx handle the HTTP connections and proxy requests to an independent
+keystone server (or servers) running under a wsgi container such as uwsgi or
+gunicorn. The typical deployment will have several applications proxied by the
+web server (for example horizon on /dashboard and keystone on /identity,
+/identity_admin, port :5000, and :35357). Proxying allows the applications to
+be shut down and restarted independently, and a problem in one application
+isn't going to affect the web server or other applications. The servers can
+easily be run in their own virtualenvs.
+
+The httpd/ directory contains sample files for configuring HTTPD to proxy
+requests to keystone servers running under uwsgi.
+
+Copy the `httpd/uwsgi-keystone.conf` sample configuration file to the
+appropriate location for your Apache server, on Debian/Ubuntu systems it is::
+
+ /etc/apache2/sites-available/uwsgi-keystone.conf
+
+On Red Hat based systems it is::
+
+ /etc/httpd/conf.d/uwsgi-keystone.conf
+
+Update the file to match your system configuration. Enable TLS by supplying the
+correct certificates.
+
+Enable mod_proxy_uwsgi.
+
+* On Ubuntu the required package is libapache2-mod-proxy-uwsgi; enable using
+ ``sudo a2enmod proxy``
+* On Fedora the required package is mod_proxy_uwsgi; enable by creating a file
+ ``/etc/httpd/conf.modules.d/11-proxy_uwsgi.conf`` containing
+ ``LoadModule proxy_uwsgi_module modules/mod_proxy_uwsgi.so``
+
+Enable the site by creating a symlink from the file in ``sites-available`` to
+``sites-enabled``, for example, on Debian/Ubuntu systems
+(not required on Red Hat based systems)::
+
+ ln -s /etc/apache2/sites-available/uwsgi-keystone.conf /etc/apache2/sites-enabled/
+
+Start or restart HTTPD to pick up the new configuration.
+
+Now configure and start the uwsgi services. Copy the
+`httpd/keystone-uwsgi-admin.ini` and `httpd/keystone-uwsgi-public.ini` files to
+`/etc/keystone`. Update the files to match your system configuration (for
+example, you'll want to set the number of threads for the public and admin
+servers).
+
+Start up the keystone servers using uwsgi::
+
+ $ sudo pip install uwsgi
+ $ uwsgi /etc/keystone/keystone-uwsgi-admin.ini
+ $ uwsgi /etc/keystone/keystone-uwsgi-public.ini
+
+
+mod_wsgi
+--------
+
.. WARNING::
- Running Keystone under HTTPD in the recommended (and tested) configuration
- does not support the use of ``Transfer-Encoding: chunked``. This is due to
- a limitation with the WSGI spec and the implementation used by
- ``mod_wsgi``. It is recommended that all clients assume Keystone will not
- support ``Transfer-Encoding: chunked``.
-
-
-Files
------
+ Running Keystone under HTTPD in this configuration does not support the use
+ of ``Transfer-Encoding: chunked``. This is due to a limitation with the
+ WSGI spec and the implementation used by ``mod_wsgi``. It is recommended
+ that all clients assume Keystone will not support
+ ``Transfer-Encoding: chunked``.
Copy the ``httpd/wsgi-keystone.conf`` sample configuration file to the
appropriate location for your Apache server, on Debian/Ubuntu systems
@@ -55,7 +111,7 @@ Enable the site by creating a symlink from the file in ``sites-available`` to
``sites-enabled``, for example, on Debian/Ubuntu systems
(not required on Red Hat based systems)::
- ln -s /etc/apache2/sites-available/keystone.conf /etc/apache2/sites-enabled/
+ ln -s /etc/apache2/sites-available/wsgi-keystone.conf /etc/apache2/sites-enabled/
Restart Apache to have it start serving keystone.
diff --git a/httpd/keystone-uwsgi-admin.ini b/httpd/keystone-uwsgi-admin.ini
new file mode 100644
index 0000000000..8624ee3e9e
--- /dev/null
+++ b/httpd/keystone-uwsgi-admin.ini
@@ -0,0 +1,22 @@
+[uwsgi]
+wsgi-file = /usr/local/bin/keystone-wsgi-admin
+
+# Versions of mod_proxy_uwsgi>=2.0.6 should use a UNIX socket, see
+# http://uwsgi-docs.readthedocs.org/en/latest/Apache.html#mod-proxy-uwsgi
+uwsgi-socket = 127.0.0.1:35358
+
+# Override the default size for headers from the 4k default.
+buffer-size = 65535
+
+# This is running standalone
+master = true
+
+enable-threads = true
+
+# Tune this to your environment.
+threads = 4
+
+# uwsgi recommends this to prevent thundering herd on accept.
+thunder-lock = true
+
+plugins = python
diff --git a/httpd/keystone-uwsgi-public.ini b/httpd/keystone-uwsgi-public.ini
new file mode 100644
index 0000000000..c952116330
--- /dev/null
+++ b/httpd/keystone-uwsgi-public.ini
@@ -0,0 +1,22 @@
+[uwsgi]
+wsgi-file = /usr/local/bin/keystone-wsgi-public
+
+# Versions of mod_proxy_uwsgi>=2.0.6 should use a UNIX socket, see
+# http://uwsgi-docs.readthedocs.org/en/latest/Apache.html#mod-proxy-uwsgi
+uwsgi-socket = 127.0.0.1:5001
+
+# Override the default size for headers from the 4k default.
+buffer-size = 65535
+
+# This is running standalone
+master = true
+
+enable-threads = true
+
+# Tune this to your environment.
+threads = 4
+
+# uwsgi recommends this to prevent thundering herd on accept.
+thunder-lock = true
+
+plugins = python
diff --git a/httpd/uwsgi-keystone.conf b/httpd/uwsgi-keystone.conf
new file mode 100644
index 0000000000..2d61a5bf57
--- /dev/null
+++ b/httpd/uwsgi-keystone.conf
@@ -0,0 +1,13 @@
+Listen 5000
+Listen 35357
+
+
+ ProxyPass / uwsgi://127.0.0.1:5001/
+
+
+
+ ProxyPass / uwsgi://127.0.0.1:35358/
+
+
+ProxyPass /identity uwsgi://127.0.0.1:5001/
+ProxyPass /identity_admin uwsgi://127.0.0.1:35358/