Gearbox comes with its own built-in web server for development but Kallithea

  defaults to using Waitress_. Gunicorn_ and Gevent_ are also options. These

  web servers have different limited feature sets.

  The web server used by ``gearbox serve`` is configured in the ``.ini`` file.

  Create it with ``config-create`` using for example ``http_server=waitress``

  to get a configuration starting point for your choice of web server.

  (Gearbox will do like ``paste`` and use the WSGI application entry point

  ``kallithea.config.application:make_app`` as specified in ``setup.py``.)

- `Apache httpd`_ can serve WSGI applications directly using mod_wsgi_ and a

  simple Python file with the necessary configuration. This is a good option if

  Apache is an option.

- uWSGI_ is also a full web server with built-in WSGI module. Use

  ``config-create`` with ``http_server=uwsgi`` to get a ``.ini`` file with

  uWSGI configuration.

- IIS_ can also server WSGI applications directly using isapi-wsgi_.

- A `reverse HTTP proxy <https://en.wikipedia.org/wiki/Reverse_proxy>`_

  can be put in front of another web server which has WSGI support.

  Such a layered setup can be complex but might in some cases be the right

  option, for example to standardize on one internet-facing web server, to add

  encryption or special authentication or for other security reasons, to

  provide caching of static files, or to provide load balancing or fail-over.

  Nginx_, Varnish_ and HAProxy_ are often used for this purpose, often in front

  of a ``gearbox serve`` that somehow is wrapped as a service.

The best option depends on what you are familiar with and the requirements for

performance and stability. Also, keep in mind that Kallithea mainly is serving

dynamically generated pages from a relatively slow Python process. Kallithea is

also often used inside organizations with a limited amount of users and thus no

continuous hammering from the internet.

.. note::

   Kallithea, the libraries it uses, and Python itself do in several places use

   simple caching in memory. Caches and memory are not always released in a way

   that is suitable for long-running processes. They might appear to be leaking

   memory. The worker processes should thus regularly be restarted - for

   example after 1000 requests and/or one hour. This can usually be done by the

   web server or the tool used for running it as a system service.

.. _Python: http://www.python.org/

.. _Gunicorn: http://gunicorn.org/

.. _Gevent: http://www.gevent.org/

.. _PyPI: https://pypi.python.org/pypi

.. _Apache httpd: http://httpd.apache.org/

.. _mod_wsgi: https://code.google.com/p/modwsgi/

.. _isapi-wsgi: https://github.com/hexdump42/isapi-wsgi

.. _nginx: http://nginx.org/en/

.. _iis: http://en.wikipedia.org/wiki/Internet_Information_Services

.. _pip: http://en.wikipedia.org/wiki/Pip_%28package_manager%29

.. _WSGI: http://en.wikipedia.org/wiki/Web_Server_Gateway_Interface

.. _HAProxy: http://www.haproxy.org/

.. _Varnish: https://www.varnish-cache.org/

.. _npm: https://www.npmjs.com/

(not necessarily with password access, but public key access must be enabled),

all file permissions must be set as sshd wants it, and ``authorized_keys`` must

be writeable by the Kallithea user.

.. note:: The ``authorized_keys`` file will be rewritten from scratch on

    each update. If it already exists with other data, Kallithea will not

    overwrite the existing ``authorized_keys``, and the server process will

    instead throw an exception. The system administrator thus cannot ssh

    directly to the Kallithea user but must use su/sudo from another account.

    If ``/home/kallithea/.ssh/`` (the directory of the path specified in the

    ``ssh_authorized_keys`` setting of the ``.ini`` file) does not exist as a

    directory, Kallithea will attempt to create it. If that path exists but is

    *not* a directory, or is not readable-writable-executable by the server

    process, the server process will raise an exception each time it attempts to

    write the ``authorized_keys`` file.

.. note:: It is possible to configure the SSH server to look for authorized

   keys in multiple files, for example reserving ``ssh/authorized_keys`` to be

   used for normal SSH and with Kallithea using

   ``.ssh/authorized_keys_kallithea``. In ``/etc/ssh/sshd_config`` set

   ``AuthorizedKeysFile .ssh/authorized_keys .ssh/authorized_keys_kallithea``

   and restart sshd, and in ``my.ini`` set ``ssh_authorized_keys =

   /home/kallithea/.ssh/authorized_keys_kallithea``. Note that this new

   location will apply to all system users, and that multiple entries for the

   same SSH key will shadow each other.

.. warning:: The handling of SSH access is steered directly by the command

    specified in the ``authorized_keys`` file. There is no interaction with the

    web UI.  Once SSH access is correctly configured and enabled, it will work

    regardless of whether the Kallithea web process is actually running. Hence,

    if you want to perform repository or server maintenance and want to fully

    disable all access to the repositories, disable SSH access by setting

    ``ssh_enabled = false`` in the correct ``.ini`` file (i.e. the ``.ini`` file

    specified in the ``authorized_keys`` file.)

The ``authorized_keys`` file can be updated manually with ``kallithea-cli

ssh-update-authorized-keys -c my.ini``. This command is not needed in normal

operation but is for example useful after changing SSH-related settings in the

``.ini`` file or renaming that file. (The path to the ``.ini`` file is used in

the generated ``authorized_keys`` file).

Setting up Whoosh full text search

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

Kallithea provides full text search of repositories using `Whoosh`__.

For an incremental index build, run::

    kallithea-cli index-create -c my.ini

For a full index rebuild, run::

    kallithea-cli index-create -c my.ini --full

The ``--repo-location`` option allows the location of the repositories to be overridden;

usually, the location is retrieved from the Kallithea database.

The ``--index-only`` option can be used to limit the indexed repositories to a comma-separated list::

    kallithea-cli index-create -c my.ini --index-only=vcs,kallithea

To keep your index up-to-date it is necessary to do periodic index builds;

for this, it is recommended to use a crontab entry. Example::

    0  3  *  *  *  /path/to/virtualenv/bin/kallithea-cli index-create -c /path/to/kallithea/my.ini

When using incremental mode (the default), Whoosh will check the last

modification date of each file and add it to be reindexed if a newer file is

available. The indexing daemon checks for any removed files and removes them

from index.

If you want to rebuild the index from scratch, you can use the ``-f`` flag as above,

or in the admin panel you can check the "build from scratch" checkbox.

Integration with issue trackers

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

Kallithea provides a simple integration with issue trackers. It's possible

to define a regular expression that will match an issue ID in commit messages,

and have that replaced with a URL to the issue.

This is achieved with following three variables in the ini file::

    issue_pat = #(\d+)

    issue_server_link = https://issues.example.com/{repo}/issue/\1

    issue_sub =

``issue_pat`` is the regular expression describing which strings in

commit messages will be treated as issue references. The expression can/should

have one or more parenthesized groups that can later be referred to in

``issue_server_link`` and ``issue_sub`` (see below). If you prefer, named groups

can be used instead of simple parenthesized groups.

determine the intended recipients, the administrators and the addresses

specified in ``email_to`` in the configuration file are used as fallback.

Recipients will see these emails originating from the sender specified in the

``app_email_from`` setting in the configuration file. This setting can either

contain only an email address, like `kallithea-noreply@example.com`, or both

a name and an address in the following format: `Kallithea

<kallithea-noreply@example.com>`. However, if the email is sent due to an

action of a particular user, for example when a comment is given or a pull

request created, the name of that user will be combined with the email address

specified in ``app_email_from`` to form the sender (and any name part in that

configuration setting disregarded).

The subject of these emails can optionally be prefixed with the value of

``email_prefix`` in the configuration file.

A Kallithea-specific header indicating the email type will be added to each

email. This header can be used for email filtering. The header is of the form:

    X-Kallithea-Notification-Type: <type>

where ``<type>`` is one of:

- ``pull_request``: you are invited as reviewer in a pull request

- ``pull_request_comment``: a comment was given on a pull request

- ``cs_comment``: a comment was given on a changeset

- ``registration``: a new user was registered

- ``message``: another type of email

Error emails

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

When an exception occurs in Kallithea -- and unless interactive debugging is

enabled using ``set debug = true`` in the ``[app:main]`` section of the

configuration file -- an email with exception details is sent by backlash_

to the addresses specified in ``email_to`` in the configuration file.

Recipients will see these emails originating from the sender specified in the

``error_email_from`` setting in the configuration file. This setting can either

contain only an email address, like `kallithea-noreply@example.com`, or both

a name and an address in the following format: `Kallithea Errors

<kallithea-noreply@example.com>`.

References

----------

.. _backlash: https://github.com/TurboGears/backlash

rm -rf build dist

hg archive build

cd build

echo "Check that each entry in MANIFEST.in match something"

sed -e 's/[^ ]*[ ]*\([^ ]*\).*/\1/g' MANIFEST.in | xargs ls -lad

echo "Build dist"

python3 setup.py compile_catalog

python3 setup.py sdist

echo "Verify VERSION from kallithea/__init__.py"

namerel=$(cd dist && echo Kallithea-*.tar.gz)

namerel=${namerel%.tar.gz}

version=${namerel#Kallithea-}

ls -l $(pwd)/dist/$namerel.tar.gz

echo "Releasing Kallithea $version in directory $namerel"

echo "Verify dist file content"

diff -u <((hg mani | grep -v '^\.hg\|^kallithea/i18n/en/LC_MESSAGES/kallithea.mo$') | LANG=C sort) <(tar tf dist/Kallithea-$version.tar.gz | sed "s|^$namerel/||" | grep . | grep -v '^kallithea/i18n/.*/LC_MESSAGES/kallithea.mo$\|^Kallithea.egg-info/\|^PKG-INFO$\|/$' | LANG=C sort)

echo "Verify docs build"

python3 setup.py build_sphinx # the results are not actually used, but we want to make sure it builds

echo "Shortlog for inclusion in the release announcement"

scripts/shortlog.py "only('.', branch('stable') & tagged() & public() & not '.')"

cat - << EOT

Now, make sure

* all tests are passing

* release note is ready

* announcement is ready

* source has been pushed to https://kallithea-scm.org/repos/kallithea

EOT

echo "Verify current revision is tagged for $version"

hg log -r "'$version'&." | grep .

echo -n "Enter \"pypi\" to upload Kallithea $version to pypi: "

read answer

[ "$answer" = "pypi" ]

echo "Rebuild readthedocs for docs.kallithea-scm.org"

xdg-open https://readthedocs.org/projects/kallithea/

curl -X POST http://readthedocs.org/build/kallithea

xdg-open https://readthedocs.org/projects/kallithea/builds

twine upload dist/*

xdg-open https://pypi.python.org/pypi/Kallithea