Mercurial > kallithea
changeset 7653:9bae11163c31 stable
docs: outline the challenges of specifying a locale for services (Issue #340)
Trying to embed the most essential parts of
http://blog.dscpl.com.au/2014/09/setting-lang-and-lcall-when-using.html and
https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIDaemonProcess.html
.
(some rewording by Thomas De Schampheleire)
| author | Mads Kiilerich <mads@kiilerich.com> |
|---|---|
| date | Wed, 01 May 2019 00:57:04 +0200 |
| parents | 759d5143042c |
| children | 0e78c9e11a72 |
| files | docs/overview.rst docs/setup.rst |
| diffstat | 2 files changed, 44 insertions(+), 2 deletions(-) [+] |
line wrap: on
line diff
--- a/docs/overview.rst Fri May 10 21:24:21 2019 +0200 +++ b/docs/overview.rst Wed May 01 00:57:04 2019 +0200 @@ -37,6 +37,41 @@ We recommend using virtualenv for installing Kallithea. +Locale environment +------------------ + +In order to ensure a correct functioning of Kallithea with respect to non-ASCII +characters in user names, file paths, commit messages, etc., it is very +important that Kallithea is run with a correct `locale` configuration. + +On Unix, environment variables like ``LANG`` or ``LC_ALL`` can specify a language (like +``en_US``) and encoding (like ``UTF-8``) to use for code points outside the ASCII +range. The flexibility of supporting multiple encodings of Unicode has the flip +side of having to specify which encoding to use - especially for Mercurial. + +It depends on the OS distribution and system configuration which locales are +available. For example, some Docker containers based on Debian default to only +supporting the ``C`` language, while other Linux environments have ``en_US`` but not +``C``. The ``locale -a`` command will show which values are available on the +current system. Regardless of the actual language, you should normally choose a +locale that has the ``UTF-8`` encoding (note that spellings ``utf8``, ``utf-8``, +``UTF8``, ``UTF-8`` are all referring to the same thing) + +For technical reasons, the locale configuration **must** be provided in the +environment in which Kallithea runs - it cannot be specified in the ``.ini`` file. +How to practically do this depends on the web server that is used and the way it +is started. For example, gearbox is often started by a normal user, either +manually or via a script. In this case, the required locale environment +variables can be provided directly in that user's environment or in the script. +However, web servers like Apache are often started at boot via an init script or +service file. Modifying the environment for this case would thus require +root/administrator privileges. Moreover, that environment would dictate the +settings for all web services running under that web server, Kallithea being +just one of them. Specifically in the case of Apache with ``mod_wsgi``, the +locale can be set for a specific service in its ``WSGIDaemonProcess`` directive, +using the ``lang`` parameter. + + Installation methods --------------------
--- a/docs/setup.rst Fri May 10 21:24:21 2019 +0200 +++ b/docs/setup.rst Wed May 01 00:57:04 2019 +0200 @@ -539,6 +539,12 @@ - Add the necessary ``WSGI*`` directives to the Apache Virtual Host configuration file, like in the example below. Notice that the WSGI dispatch script created above is referred to with the ``WSGIScriptAlias`` directive. + The default locale settings Apache provides for web services are often not + adequate, with `C` as the default language and `ASCII` as the encoding. + Instead, use the ``lang`` parameter of ``WSGIDaemonProcess`` to specify a + suitable locale. See also the :ref:`overview` section and the + `WSGIDaemonProcess documentation`_. + Apache will by default run as a special Apache user, on Linux systems usually ``www-data`` or ``apache``. If you need to have the repositories directory owned by a different user, use the user and group options to @@ -549,7 +555,7 @@ .. code-block:: apache WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100 \ - python-home=/srv/kallithea/venv + python-home=/srv/kallithea/venv lang=C.UTF-8 WSGIProcessGroup kallithea WSGIScriptAlias / /srv/kallithea/dispatch.wsgi WSGIPassAuthorization On @@ -558,7 +564,7 @@ .. code-block:: apache - WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100 + WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100 lang=en_US.utf8 WSGIProcessGroup kallithea WSGIScriptAlias / /srv/kallithea/dispatch.wsgi WSGIPassAuthorization On @@ -583,3 +589,4 @@ .. _Redis: http://redis.io/ .. _mercurial-server: http://www.lshift.net/mercurial-server.html .. _PublishingRepositories: https://www.mercurial-scm.org/wiki/PublishingRepositories +.. _WSGIDaemonProcess documentation: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIDaemonProcess.html