Add Apache/uWSGI configuration examples

This change[1] allowed Qinling API to be used with Apache mod_wsgi and uWSGI.

Using Apache/uWSGI is the best approach for a production environment,
Apache virtualhost and uWSGI examples are available into
etc/{apache2|uwsgi} directory.

[1] https://review.opendev.org/#/c/661851/

Change-Id: I052ff1a674529539db82947150b32ed564e939f8
Story: 2005920
Task: 34194

doc/source/contributor/index.rst

@@ -27,6 +27,7 @@ project.
 
     development-environment-devstack
     architecture
+    Setting up your development Apache mod_wsgi/uWSGI <mod-wsgi>
     contributing
 
 Indices and tables

doc/source/contributor/mod-wsgi.rst

@@ -0,0 +1,100 @@
+..
+      Licensed under the Apache License, Version 2.0 (the "License"); you may
+      not use this file except in compliance with the License. You may obtain
+      a copy of the License at
+
+          http://www.apache.org/licenses/LICENSE-2.0
+
+      Unless required by applicable law or agreed to in writing, software
+      distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
+      WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
+      License for the specific language governing permissions and limitations
+      under the License.
+
+
+============================
+ Installing the API via WSGI
+============================
+
+This document provides two WSGI methods as examples:
+
+* uWSGI
+* Apache ``mod_wsgi``
+
+.. seealso::
+
+    https://governance.openstack.org/tc/goals/pike/deploy-api-in-wsgi.html#uwsgi-vs-mod-wsgi
+
+
+The "wsgi.py" file
+==================
+
+``qinling/api/wsgi.py`` file sets up the API WSGI application, it has to be copied into ``/var/www/cgi-bin/qinling`` directory.
+
+.. code-block:: console
+
+   mkdir -p /var/www/cgi-bin/qinling
+   cp qinling/api/wsgi.py /var/www/cgi-bin/qinling
+   chown qinling:qinling -R /var/www/cgi-bin/qinling
+
+
+Running with Apache and mod_wsgi
+================================
+
+The ``etc/apache2/qinling-api.conf`` file  contains an example
+of Apache virtualhost configured with ``mod_wsgi``.
+
+.. literalinclude:: ../../../etc/apache2/qinling-api.conf
+
+1. On deb-based systems copy or symlink the file to
+   ``/etc/apache2/sites-available``.
+
+   For rpm-based systems the file will go in
+   ``/etc/httpd/conf.d``.
+
+2. Modify the ``WSGIDaemonProcess`` directive to set the ``user`` and
+   ``group`` values to an appropriate user on your server. In many
+   installations ``qinling`` will be correct. Modify the ``WSGIScriptAlias``
+   directive to set the path of the wsgi script.
+
+   If you are using a virtualenv ``WSGIDaemonProcess`` requires
+   ``python-path`` parameter, the value should be
+   ``<your-venv-path>/lib/python<your-version>/site-packages``.
+
+3. Enable the ``qinling-api`` virtualhost.
+
+   On deb-based systems:
+
+   .. code-block:: console
+
+      a2ensite qinling-api
+      systemctl reload apache2
+
+   On rpm-based systems:
+
+   .. code-block:: console
+
+      systemctl reload httpd
+
+
+Running with uWSGI
+==================
+
+The ``etc/uwsgi/qinling-api.yaml`` file contains an example
+of uWSGI configuration.
+
+1. Create the ``qinling-api.yaml`` file.
+
+   .. literalinclude:: ../../../etc/uwsgi/qinling-api.yaml
+
+2. Then start the uWSGI server:
+
+   .. code-block:: console
+
+      uwsgi ./qinling-api.yaml
+
+   Or start in background with:
+
+   .. code-block:: console
+
+      uwsgi -d ./qinling-api.yaml

etc/apache2/qinling-api.conf

@@ -0,0 +1,48 @@
+# Qinling API port
+Listen 7070
+
+#################
+# Hardening 1/2 #
+#################
+ServerSignature Off
+ServerTokens Prod
+TraceEnable off
+
+<VirtualHost *:7070>
+
+  DocumentRoot "/var/www/cgi-bin/qinling"
+
+  # Avoid this issue: https://bugs.launchpad.net/charm-heat/+bug/1717615
+  AllowEncodedSlashes On
+
+  ###########
+  # Logging #
+  ###########
+  # Paths have to be changed to fit your deployment
+  ErrorLog "/var/log/apache2/qinling_wsgi_error.log"
+  LogFormat "%{X-Forwarded-For}i %l %u %t \"%r\" %>s %b %D \"%{Referer}i\" \"%{User-Agent}i\"" logformat
+  CustomLog "/var/log/apache2/qinling_wsgi_access.log" logformat
+
+  ######################
+  # WSGI configuration #
+  ######################
+  WSGIApplicationGroup %{GLOBAL}
+  # Paths and user/group have to be changed to fit your deployment
+  # Here Python 3.6 is issued.
+  WSGIDaemonProcess qinling group=qinling processes=5 threads=1 user=qinling python-path=/var/lib/kolla/venv/lib/python3.6/site-packages
+  WSGIProcessGroup qinling
+  WSGIScriptAlias / "/var/www/cgi-bin/qinling/wsgi.py"
+  WSGIPassAuthorization On
+
+  #################
+  # Hardening 2/2 #
+  #################
+  # Paths have to be changed to fit your deployment
+  <Directory "/var/www/cgi-bin/qinling">
+      <FilesMatch "^wsgi.py$">
+        Options Indexes FollowSymLinks MultiViews
+        Require all granted
+      </FilesMatch>
+  </Directory>
+
+</VirtualHost>

etc/uwsgi/qinling-api.yaml

@@ -0,0 +1,29 @@
+uwsgi:
+  http-socket: 0.0.0.0:7070
+  # Paths have to be changed to fit your deployment
+  wsgi-file: /var/www/cgi-bin/qinling/wsgi.py
+  chdir: /var/lib/kolla/venv/lib/python3.6/site-packages
+  pythonpath: /var/lib/kolla/venv/lib/python3.6/site-packages
+  virtualenv: /var/lib/kolla/venv
+
+  plugins: python3
+  # Set uid and gip to a appropriate user on your server. In many
+  # installations qinling will be correct
+  uid: qinling
+  gid: qinling
+
+  processes: 5
+  threads: 1
+  vacuum: true
+  harakiri: 20
+  buffer-size: 65535
+  post-buffering: 8192
+  # Set die-on-term and exit-on-reload so that uWSGI shuts down
+  die-on-term: true
+  exit-on-reload: true
+  master: true
+  enable-threads: true
+  # uWSGI recommends this to prevent thundering herd on accept
+  thunder-lock: true
+  honour-stdin: true
+  memory-report: false

releasenotes/notes/add-apache-uwsgi-examples-13f735ec82c37a64.yaml

@@ -0,0 +1,12 @@
+---
+features:
+  - |
+    This `change <https://review.opendev.org/#/c/661851/>`__ allowed Qinling
+    API to be used with Apache ``mod_wsgi`` and uWSGI.
+
+    Using Apache/uWSGI is the best approach for a production environment, Apache
+    virtualhost and uWSGI examples are available into ``etc/{apache2|uwsgi}`` directory.
+
+    See `Qinling documentation
+    <https://docs.openstack.org/qinling/latest/contributor/contributor/mod-wsgi.html>`__
+    for details.