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: 34194changes/37/666737/8
@ -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 |
@ -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> |
@ -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 |
@ -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. |