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.

  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`_.

          python-home=/srv/kallithea/venv lang=C.UTF-8

      WSGIDaemonProcess kallithea processes=5 threads=1 maximum-requests=100 lang=en_US.utf8

.. _WSGIDaemonProcess documentation: https://modwsgi.readthedocs.io/en/develop/configuration-directives/WSGIDaemonProcess.html