Add a guide to deploy Neutron API under WSGI server

Change-Id: Ia6c707756ec0142f9e95610ea4e21d7269934d9c
Partially-implements: blueprint run-in-wsgi-server

doc/source/admin/config-wsgi.rst

@@ -0,0 +1,129 @@
+.. _config-wsgi:
+
+Installing Neutron API via WSGI
+===============================
+
+This document is a guide to deploying neutron using WSGI. There are two ways to
+deploy using WSGI: ``uwsgi`` and Apache ``mod_wsgi``.
+
+Please note that if you intend to use mode uwsgi, you should install the
+``mode_proxy_uwsgi`` module. For example on deb-based system:
+
+.. code-block:: console
+
+    # sudo apt-get install libapache2-mod-proxy-uwsgi
+    # sudo a2enmod proxy
+    # sudo a2enmod proxy_uwsgi
+
+.. end
+
+WSGI Application
+----------------
+
+The function ``neutron.server.get_application`` will setup a WSGI application
+to run behind uwsgi and mod_wsgi.
+
+Neutron API behind uwsgi
+------------------------
+
+Create a ``/etc/neutron/neutron-api-uwsgi.ini`` file with the content below:
+
+.. code-block:: ini
+
+    [uwsgi]
+    chmod-socket = 666
+    socket = /var/run/uwsgi/neutron-api.socket
+    lazy-apps = true
+    add-header = Connection: close
+    buffer-size = 65535
+    hook-master-start = unix_signal:15 gracefully_kill_them_all
+    thunder-lock = true
+    plugins = python
+    enable-threads = true
+    worker-reload-mercy = 90
+    exit-on-reload = false
+    die-on-term = true
+    master = true
+    processes = 2
+    wsgi-file = <path-to-neutron-bin-dir>/neutron-api
+
+.. end
+
+Start neutron-api:
+
+.. code-block:: console
+
+    # uwsgi --procname-prefix neutron-api --ini /etc/neutron/neutron-api-uwsgi.ini
+
+.. end
+
+Neutron API behind mod_wsgi
+---------------------------
+
+Create ``/etc/apache2/neutron.conf`` with content below:
+
+.. code-block:: ini
+
+    Listen 9696
+    LogFormat "%h %l %u %t \"%r\" %>s %b \"%{Referer}i\" \"%{User-agent}i\" %D(us)" neutron_combined
+
+    <Directory /usr/local/bin>
+        Require all granted
+    </Directory>
+
+    <VirtualHost *:9696>
+        WSGIDaemonProcess neutron-server processes=1 threads=1 user=stack display-name=%{GROUP}
+        WSGIProcessGroup neutron-server
+        WSGIScriptAlias / <path-to-neutron-bin-dir>/neutron-api
+        WSGIApplicationGroup %{GLOBAL}
+        WSGIPassAuthorization On
+        ErrorLogFormat "%M"
+        ErrorLog /var/log/neutron/neutron.log
+        CustomLog /var/log/neutron/neutron_access.log neutron_combined
+    </VirtualHost>
+
+    Alias /networking <path-to-neutron-bin-dir>/neutron-api
+    <Location /networking>
+        SetHandler wsgi-script
+        Options +ExecCGI
+        WSGIProcessGroup neutron-server
+        WSGIApplicationGroup %{GLOBAL}
+        WSGIPassAuthorization On
+    </Location>
+
+    WSGISocketPrefix /var/run/apache2
+
+.. end
+
+For deb-based systems copy or symlink the file to ``/etc/apache2/sites-available``.
+Then enable the neutron site:
+
+.. code-block:: console
+
+    # a2ensite neutron
+    # systemctl reload apache2.service
+
+.. end
+
+For rpm-based systems copy the file to ``/etc/httpd/conf.d``. Then enable the
+neutron site:
+
+.. code-block:: console
+
+    # systemctl reload httpd.service
+
+.. end
+
+
+Start Neutron RPC server
+------------------------
+
+When Neutron API is served by a web server (like Apache2) it is difficult
+to start an rpc listener thread. So start the Neutron RPC server process to
+serve this job:
+
+.. code-block:: console
+
+    # /usr/bin/neutron-rpc-server --config-file /etc/neutron/neutron.conf --config-file /etc/neutron/plugins/ml2/ml2_conf.ini
+
+.. end

doc/source/admin/config.rst

@@ -35,6 +35,7 @@ Configuration
    config-subnet-pools
    config-service-subnets
    config-trunking
+   config-wsgi
 
 .. note::