diff --git a/doc/source/contributor/index.rst b/doc/source/contributor/index.rst index d1b6bf6b..c713793c 100644 --- a/doc/source/contributor/index.rst +++ b/doc/source/contributor/index.rst @@ -27,6 +27,7 @@ project. development-environment-devstack architecture + Setting up your development Apache mod_wsgi/uWSGI contributing Indices and tables diff --git a/doc/source/contributor/mod-wsgi.rst b/doc/source/contributor/mod-wsgi.rst new file mode 100644 index 00000000..43e2fc37 --- /dev/null +++ b/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 + ``/lib/python/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 diff --git a/etc/apache2/qinling-api.conf b/etc/apache2/qinling-api.conf new file mode 100644 index 00000000..e39dcee5 --- /dev/null +++ b/etc/apache2/qinling-api.conf @@ -0,0 +1,48 @@ +# Qinling API port +Listen 7070 + +################# +# Hardening 1/2 # +################# +ServerSignature Off +ServerTokens Prod +TraceEnable off + + + + 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 + + + Options Indexes FollowSymLinks MultiViews + Require all granted + + + + diff --git a/etc/uwsgi/qinling-api.yaml b/etc/uwsgi/qinling-api.yaml new file mode 100644 index 00000000..561554e5 --- /dev/null +++ b/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 diff --git a/releasenotes/notes/add-apache-uwsgi-examples-13f735ec82c37a64.yaml b/releasenotes/notes/add-apache-uwsgi-examples-13f735ec82c37a64.yaml new file mode 100644 index 00000000..8ef46844 --- /dev/null +++ b/releasenotes/notes/add-apache-uwsgi-examples-13f735ec82c37a64.yaml @@ -0,0 +1,12 @@ +--- +features: + - | + This `change `__ 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 + `__ + for details.