Issue #203: Documentation for mod_wsgi has a number of mistakes. (conservancy/kallithea)

[Graham Dumpleton]

New issue 203: Documentation for mod_wsgi has a number of mistakes.
https://bitbucket.org/conservancy/kallithea/issues/203/documentation-for-mod_wsgi-has-a-number-of

Graham Dumpleton:

Documentation at:

* http://kallithea.readthedocs.org/en/0.3.1/setup.html?highlight=apache#apache-with-mod-wsgi

has the following errors.

1 - Two sample mod_wsgi configuration are give of:


```
WSGIDaemonProcess kallithea \
    processes=1 threads=4 \
    python-path=/srv/kallithea/venv/lib/python2.7/site-packages
WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
WSGIPassAuthorization On
```

and

```
WSGIDaemonProcess kallithea processes=1 threads=4
WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
WSGIPassAuthorization On
```

Both examples are missing the directive:

```
WSGIProcessGroup kallithea
```

This is necessary as otherwise although a mod_wsgi daemon process group was defined, requests will not be delegated and run in the mod_wsgi daemon process group. The result will be that things appear to work, but code will be running in the Apache child worker processes. This is not ideal and would actually be a bad idea if using Apache prefork MPM or event MPM with single threaded Apache child worker processes. The result would be way more copies of Kallithea than expect, with potential to run out of memory if Apache decides to spin up more child worker processes.

As well as adding the ``WSGIProcessGroup`` directive, recommended that also set:

```
WSGIRestrictedEmbedded On
```

This turns off initialisation of Python interpreter in Apache child worker processes, saving memory and decreasing startup time of child worker processes.

This latter directive needs to be set out of the ``VirtualHost`` at global Apache configuration scope.

2 - The ``processes=1`` option to ``WSGIDaemonProcess`` is redundant as that is the default. It is important not to supply it though as by adding it as done that results in ``wsgi.multiprocess`` being set ``False`` in WSGI ``environ`` for requests. This would be an issue if you happened to scale Kallithea across multiple hosts, and something was relying on ``wsgi.multiprocess`` being correct. It would be correct if scaled horizontally out to more hosts. The default, of not supplying ``processes`` option leaves ``wsgi.multiprocess`` as ``True`` meaning no potential for issues if scaling out to more hosts.

3 - The statement:

"""
Note When running apache as root, please make sure it doesn’t run Kallithea as root, for examply by adding: user=www-data group=www-data to the configuration.
"""

is wrong.

Even if Apache is started as ``root`` so it can bind port 80, neither the child worker processes, or mod_wsgi daemon processes ever run as ``root``. Apache always drops privileges before anything actually runs. As a result, Apache will always run applications as the Apache user, which for many systems is ``www-data``. There is never any need to set user or group to ``www-data`` explicitly.

What the note should really say is:

"""
Note: Apache will by default run as a special Apache user, on Linux systems usually ``www-data``. If you need to have the repositories directory owned by a different user, use the ``user`` and ``group`` options to ``WSGIDaemonProcess`` to set the name of the user and group.
"""

4 - If using a Python virtual environment, rather than use the ``python-path`` option to specify the location of the Python virtual environment ``site-packages`` directory, it is better to use the ``python-home`` directory and give it the path to the root of the Python virtual environment. That is, whatever ``sys.prefix`` is for the installation.

This negates the need to do Python virtual environment activate in the WSGI script file.

The final configuration you really want to use where using a Python virtual environment is therefore:

```
WSGIDaemonProcess kallithea \
    processes=1 threads=4 \
    python-home=/srv/kallithea/venv
WSGIProcessGroup kallithea
WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
WSGIPassAuthorization On
```


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.sfconservancy.org/pipermail/kallithea-general/attachments/20160403/02d5511e/attachment.html>