Document running in uwsgi proxied by apache

Add documentation for how to run uwsgi proxied by uwsgi.

Change-Id: I3d307a953bbe1ba78745c0846cd4c5a78010b6cb

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.
 

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

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

httpd/uwsgi-keystone.conf

@@ -0,0 +1,13 @@
+Listen 5000
+Listen 35357
+
+<VirtualHost *:5000>
+    ProxyPass / uwsgi://127.0.0.1:5001/
+</VirtualHost>
+
+<VirtualHost *:35357>
+    ProxyPass / uwsgi://127.0.0.1:35358/
+</VirtualHost>
+
+ProxyPass /identity uwsgi://127.0.0.1:5001/
+ProxyPass /identity_admin uwsgi://127.0.0.1:35358/