Changeset - 9bae11163c31
Parent rev.
Child rev.
[Not reviewed]
stable
0 2 0
Mads Kiilerich - 7 years ago 2019-05-01 00:57:04
mads@kiilerich.com
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)
2 files changed with 44 insertions and 2 deletions:
docs/overview.rst
35
docs/setup.rst
9
2
0 comments (0 inline, 0 general)
docs/overview.rst
➞
Show inline comments
 
.. _overview:
 

			




	
	
	
		
 
=====================

			




	
	
	
		
 
Installation overview

			




	
	
	
		
 
=====================

			




	
	
	
		
 

			




	
	
	
		
 
Some overview and some details that can help understanding the options when

			




	
	
	
		
 
installing Kallithea.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Python environment

			




	
	
	
		
 
------------------

			




	
	
	
		
 

			




	
	
	
		
 
**Kallithea** is written entirely in Python_ and requires Python version

			




	
	
	
		
 
2.6 or higher. Python 3.x is currently not supported.

			




	
	
	
		
 

			




	
	
	
		
 
Given a Python installation, there are different ways of providing the

			




	
	
	
		
 
environment for running Python applications. Each of them pretty much

			




	
	
	
		
 
corresponds to a ``site-packages`` directory somewhere where packages can be

			




	
	
	
		
 
installed.

			




	
	
	
		
 

			




	
	
	
		
 
Kallithea itself can be run from source or be installed, but even when running

			




	
	
	
		
 
from source, there are some dependencies that must be installed in the Python

			




	
	
	
		
 
environment used for running Kallithea.

			




	
	
	
		
 

			




	
	
	
		
 
- Packages *could* be installed in Python's ``site-packages`` directory ... but

			




	
	
	
		
 
  that would require running pip_ as root and it would be hard to uninstall or

			




	
	
	
		
 
  upgrade and is probably not a good idea unless using a package manager.

			




	
	
	
		
 

			




	
	
	
		
 
- Packages could also be installed in ``~/.local`` ... but that is probably

			




	
	
	
		
 
  only a good idea if using a dedicated user per application or instance.

			




	
	
	
		
 

			




	
	
	
		
 
- Finally, it can be installed in a virtualenv_. That is a very lightweight

			




	
	
	
		
 
  "container" where each Kallithea instance can get its own dedicated and

			




	
	
	
		
 
  self-contained virtual environment.

			




	
	
	
		
 

			




	
	
	
		
 
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

			




	
	
	
		
 
--------------------

			




	
	
	
		
 

			




	
	
	
		
 
Kallithea must be installed on a server. Kallithea is installed in a Python

			




	
	
	
		
 
environment so it can use packages that are installed there and make itself

			




	
	
	
		
 
available for other packages.

			




	
	
	
		
 

			




	
	
	
		
 
Two different cases will pretty much cover the options for how it can be

			




	
	
	
		
 
installed.

			




	
	
	
		
 

			




	
	
	
		
 
- The Kallithea source repository can be cloned and used -- it is kept stable and

			




	
	
	
		
 
  can be used in production. The Kallithea maintainers use the development

			




	
	
	
		
 
  branch in production. The advantage of installation from source and regularly

			




	
	
	
		
 
  updating it is that you take advantage of the most recent improvements. Using

			




	
	
	
		
 
  it directly from a DVCS also means that it is easy to track local customizations.

			




	
	
	
		
 

			




	
	
	
		
 
  Running ``pip install -e .`` in the source will use pip to install the

			




	
	
	
		
 
  necessary dependencies in the Python environment and create a

			




	
	
	
		
 
  ``.../site-packages/Kallithea.egg-link`` file there that points at the Kallithea

			




	
	
	
		
 
  source.

			




	
	
	
		
 

			




	
	
	
		
 
- Kallithea can also be installed from ready-made packages using a package manager.

			




	
	
	
		
 
  The official released versions are available on PyPI_ and can be downloaded and

			




	
	
	
		
 
  installed with all dependencies using ``pip install kallithea``.

			




	
	
	
		
 

			




	
	
	
		
 
  With this method, Kallithea is installed in the Python environment as any

			




	
	
	
		
 
  other package, usually as a ``.../site-packages/Kallithea-X-py2.7.egg/``

			




	
	
	
		
 
  directory with Python files and everything else that is needed.

			




	
	
	
		
 

			




	
	
	
		
 
  (``pip install kallithea`` from a source tree will do pretty much the same

			




	
	
	
		
 
  but build the Kallithea package itself locally instead of downloading it.)

			




	
	
	
		
 

			




	
	
	
		
 
.. note::

			




	
	
	
		
 
   Kallithea includes front-end code that needs to be processed first.

			




	
	
	
		
 
   The tool npm_ is used to download external dependencies and orchestrate the

			




	
	
	
		
 
   processing. The ``npm`` binary must thus be available.

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Web server

			




	
	
	
		
 
----------

			




	
	
	
		
 

			




	
	
	
		
 
Kallithea is (primarily) a WSGI_ application that must be run from a web

			




	
	
	
		
 
server that serves WSGI applications over HTTP.

			




	
	
	
		
 

			




	
	
	
		
 
Kallithea itself is not serving HTTP (or HTTPS); that is the web server's

			




	
	
	
		
 
responsibility. Kallithea does however need to know its own user facing URL

			




	
	
	
		
 
(protocol, address, port and path) for each HTTP request. Kallithea will

			




	
	
	
		
 
usually use its own HTML/cookie based authentication but can also be configured

			




        

    


    
    

    

        

                

                    docs/setup.rst
                

                

                  
                      
                        

                      ➞

                      
                        
                  

                  
                      
                  
                      
                  
                      
                  
                      
                  
                  
                

                

                    Show inline comments
                    
                

        

        

            



	
	
		
 
@@ -494,92 +494,99 @@ that, you'll need to:

			




	
	
	
		
 
    a2enmod wsgi

			




	
	
	
		
 

			




	
	
	
		
 
- Add global Apache configuration to tell mod_wsgi that Python only will be

			




	
	
	
		
 
  used in the WSGI processes and shouldn't be initialized in the Apache

			




	
	
	
		
 
  processes::

			




	
	
	
		
 

			




	
	
	
		
 
    WSGIRestrictEmbedded On

			




	
	
	
		
 

			




	
	
	
		
 
- Create a WSGI dispatch script, like the one below. Make sure you

			




	
	
	
		
 
  check that the paths correctly point to where you installed Kallithea

			




	
	
	
		
 
  and its Python Virtual Environment.

			




	
	
	
		
 

			




	
	
	
		
 
  .. code-block:: python

			




	
	
	
		
 

			




	
	
	
		
 
      import os

			




	
	
	
		
 
      os.environ['PYTHON_EGG_CACHE'] = '/srv/kallithea/.egg-cache'

			




	
	
	
		
 

			




	
	
	
		
 
      # sometimes it's needed to set the current dir

			




	
	
	
		
 
      os.chdir('/srv/kallithea/')

			




	
	
	
		
 

			




	
	
	
		
 
      import site

			




	
	
	
		
 
      site.addsitedir("/srv/kallithea/venv/lib/python2.7/site-packages")

			




	
	
	
		
 

			




	
	
	
		
 
      ini = '/srv/kallithea/my.ini'

			




	
	
	
		
 
      from logging.config import fileConfig

			




	
	
	
		
 
      fileConfig(ini)

			




	
	
	
		
 
      from paste.deploy import loadapp

			




	
	
	
		
 
      application = loadapp('config:' + ini)

			




	
	
	
		
 

			




	
	
	
		
 
  Or using proper virtualenv activation:

			




	
	
	
		
 

			




	
	
	
		
 
  .. code-block:: python

			




	
	
	
		
 

			




	
	
	
		
 
      activate_this = '/srv/kallithea/venv/bin/activate_this.py'

			




	
	
	
		
 
      execfile(activate_this, dict(__file__=activate_this))

			




	
	
	
		
 

			




	
	
	
		
 
      import os

			




	
	
	
		
 
      os.environ['HOME'] = '/srv/kallithea'

			




	
	
	
		
 

			




	
	
	
		
 
      ini = '/srv/kallithea/kallithea.ini'

			




	
	
	
		
 
      from logging.config import fileConfig

			




	
	
	
		
 
      fileConfig(ini)

			




	
	
	
		
 
      from paste.deploy import loadapp

			




	
	
	
		
 
      application = loadapp('config:' + ini)

			




	
	
	
		
 

			




	
	
	
		
 
- 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

			




	
	
	
		
 
  WSGIDaemonProcess to set the name of the user and group.

			




	
	
	
		
 

			




	
	
	
		
 
  Once again, check that all paths are correctly specified.

			




	
	
	
		
 

			




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

			




	
	
	
		
 

			




	
	
	
		
 
  Or if using a dispatcher WSGI script with proper virtualenv activation:

			




	
	
	
		
 

			




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

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
Other configuration files

			




	
	
	
		
 
-------------------------

			




	
	
	
		
 

			




	
	
	
		
 
A number of `example init.d scripts`__ can be found in

			




	
	
	
		
 
the ``init.d`` directory of the Kallithea source.

			




	
	
	
		
 

			




	
	
	
		
 
.. __: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/ .

			




	
	
	
		
 

			




	
	
	
		
 

			




	
	
	
		
 
.. _virtualenv: http://pypi.python.org/pypi/virtualenv

			




	
	
	
		
 
.. _python: http://www.python.org/

			




	
	
	
		
 
.. _Python regular expression documentation: https://docs.python.org/2/library/re.html

			




	
	
	
		
 
.. _Mercurial: https://www.mercurial-scm.org/

			




	
	
	
		
 
.. _Celery: http://celeryproject.org/

			




	
	
	
		
 
.. _Celery documentation: http://docs.celeryproject.org/en/latest/getting-started/index.html

			




	
	
	
		
 
.. _RabbitMQ: http://www.rabbitmq.com/

			




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

			




        

    



    


    



    



      

      





    
    0 comments (0 inline, 0 general)
    





    


  

  







  


    




    








    
        
    
    
        This site is powered by
            Kallithea 0.7.0,
        which is
        © 2010–2025 by various authors & licensed under GPLv3.