.. note:: You need to have Sphinx_ installed to build the

          documentation. If you don't have Sphinx_ installed you can

          install it via the command: ``pip install sphinx`` .

Kallithea has a simple JSON RPC API with a single schema for calling all API

decorated with the ``@LoginRequired`` decorator. Some views use

``@LoginRequired(api_access=True)`` and are always available. By default only

``api_access_controllers_whitelist`` option in your .ini file and define views

GET parameter ``?api_key=<api_key>`` to the URL.

All responses from API will be ``HTTP/1.0 200 OK``. If there is an error,

Kallithea comes with a ``kallithea-api`` command line tool providing a convenient

For example, to call ``get_repo``::

Oops, looks like we forgot to add an argument. Let's try again, now

providing the ``repoid`` as a parameter::

To avoid specifying ``apihost`` and ``apikey`` every time, run::

This will create a ``~/.config/kallithea`` with the specified hostname and apikey

Rescan repositories. If ``remove_obsolete`` is set,

Kallithea will delete repos that are in the database but not in the filesystem.

Invalidate the cache for a repository.

If the param ``userid`` is skipped, it is set to the ID of the user who is calling this method.

If param ``locked`` is skipped, the current lock state of the repository is returned.

Delete the given user if such a user exists.

Adds a user to a user group. If the user already is in that group, success will be

``false``.

be ``false``.

either users_group or users associated to that repository.

It is possible to specify ret_type to show only ``files`` or ``dirs``.

Create a repository. If the repository name contains "/", all needed repository

Create a fork of the given repo. If using Celery, this will

return success message immediately and a fork will be created

When ``forks`` param is set it is possible to detach or delete forks of the deleted repository.

Grant permission for a user on the given repository, or update the existing one if found.

Revoke permission for a user on the given repository.

Grant permission for a user group on the given repository, or update the

Revoke permission for a user group on the given repository.

issue tracker is for tracking bugs, not for support, discussion, or ideas -

  have to remove its dependencies manually and make sure that they are not

An additional benefit of virtualenv_ is that it doesn't require root privileges.

  for example, in `/srv/kallithea/venv`, using the virtualenv command::

- Go into the created directory and run this command to install Kallithea::

- This will install Kallithea together with pylons_ and all other required

   It is strongly recommended that you **always** perform a database and

   These directions will use '{version}' to note that this is the version of

   backed up to ``my.ini.0-1``.

Ensure that you are using the Python virtual environment that you originally

installed Kallithea in by running::

This will list all packages installed in the current environment.  If

Kallithea isn't listed, activate the correct virtual environment::

current configuration. It will try to perform an automerge. It is recommended

that you recheck the content after the automerge.

   Please always make sure your .ini files are up to date. Errors can

   often be caused by missing parameters added in new versions.

   The DB schema upgrade library has some limitations and can sometimes fail if you try to

   upgrade from older major releases. In such a case simply run upgrades sequentially, e.g.,

   upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X

.. _pylons: http://www.pylonsproject.org/

.. warning:: Python 3.x is not supported.

While writing this guide, the latest version was v2.7.9.

Add Python BIN folder to the path. This can be done manually (editing

"PATH" environment variable) or by using Windows Support Tools that

come pre-installed in Windows Vista/7 and later.

Please substitute [your-python-path] with your Python installation

path. Typically this is ``C:\\Python27``.

Step 3 - Install pywin32 extensions

- Choose the file ending with ".amd64-py2.x.exe" (".win32-py2.x.exe"

  for Win32) where x is the minor version of Python you installed.

  When writing this guide, the file was:

  http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win-amd64-py2.7.exe/download

  (x64)

  http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win32-py2.7.exe/download

  (Win32)

.. note::

   See http://stackoverflow.com/questions/4750806/how-to-install-pip-on-windows

   for details and alternative methods.

Note that pip.exe will be placed inside your Python installation's

Scripts folder, which is likely not on your path. To correct this,

open a CMD and type::

This is only an example to install Kallithea. Of course, you can

change it. However, this guide will follow the proposed structure, so

please later adapt the paths if you change them. Folders without

spaces are recommended.

   It is strongly recommended to use it to ensure that Kallithea does not change a dependency that other software uses or vice versa.

In order to install Kallithea, you need to be able to run "pip install kallithea". It will use pip to install the Kallithea Python package and its dependencies.

.. note:: This will take some time. Please wait patiently until it is fully

          complete. Some warnings will appear. Don't worry, they are

          normal.

You have to use the same command prompt as in Step 7, so if you closed

it, reopen it following the same commands (including the "activate"

one). When ready, type::

Then you must edit production.ini to fit your needs (IP address, IP

port, mail settings, database, etc.). `NotePad++`__ or a similar text

editor is recommended to properly handle the newline character

differences between Unix and Windows.

__ http://notepad-plus-plus.org/

For the sake of simplicity, run it with the default settings. After your edits (if any) in the previous command prompt, type::

.. warning:: This time a *new* database will be installed. You must

             follow a different step to later *upgrade* to a newer

             Kallithea version)

The script will ask you for confirmation about creating a new database, answer yes (y)

The script will ask you for the repository path, answer C:\\Kallithea\\Repos (or similar).

The script will ask you for the admin username and password, answer "admin" + "123456" (or whatever you want)

The script will ask you for admin mail, answer "admin@xxxx.com" (or whatever you want).

What this guide does not cover:

Then run::

Next, update the database::

More details can be found in `<upgrade.html>`_.

following command to do so::

This will create the file ``my.ini`` in the current directory. This

configuration file contains the various settings for Kallithea, e.g.,

proxy port, email settings, usage of static files, cache, Celery

settings, and logging.

default, ensure you properly adjust the database URL in your ``my.ini``

The setup process can be fully automated, example for lazy::

The ``setup-db`` command will create all of the needed tables and an

admin account. When choosing a root path you can either use a new

empty location, or a location which already contains existing

repositories. If you choose a location which contains existing

repositories Kallithea will add all of the repositories at the chosen

location to its database.  (Note: make sure you specify the correct

path to the root).

.. note:: the given path for Mercurial_ repositories **must** be write

          accessible for the application. It's very important since

          the Kallithea web interface will work without write access,

          but when trying to do a push it will fail with permission

          denied errors unless it has write access.

You are now ready to use Kallithea. To run it simply execute::

- This command runs the Kallithea server. The web app should be available at

  http://127.0.0.1:5000. This ip and port is configurable via the my.ini

- In the admin panel you can toggle LDAP, anonymous, and permissions

  settings, as well as edit more advanced options on users and

  repositories

Optionally users can create an ``rcextensions`` package that extends Kallithea

This will create an ``rcextensions`` package in the same place that your ``ini`` file

lives. With ``rcextensions`` it's possible to add additional mapping for whoosh,

stats and add additional code into the push/pull/create/delete repo hooks,

for example, for sending signals to build-bots such as Jenkins.

Please see the ``__init__.py`` file inside ``rcextensions`` package

In order to use ssh you need to make sure that your web server and the users'

.. note:: These permissions are independent of any permissions you

          have set up using the Kallithea web interface.

If your main directory (the same as set in Kallithea settings) is for

example set to ``/srv/repos`` and the repository you are using is

named ``kallithea``, then to clone via ssh you should run::

Using other external tools such as mercurial-server_ or using ssh key-based

.. note:: In an advanced setup, in order for your ssh access to use

          the same permissions as set up via the Kallithea web

          interface, you can create an authentication hook to connect

          to the Kallithea db and run check functions for permissions

          against that.

The whoosh index can be built by using the paster

repositories (``--repo-location``).  If not specified, this value is retrieved

repositories (``--index-only``) to build index only on chooses repositories

You may optionally pass the option ``-f`` to enable a full index rebuild. Without

the ``-f`` option, indexing will run always in "incremental" mode.

Building an index for just selected repositories is possible with such command::

In order to do periodic index builds and keep your index always up to

date, it is recommended to use a crontab entry.  An example entry

might look like this::

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

available via pypi, so you can install it by running::

.. note:: ``python-ldap`` requires some libraries to be installed on

          your system, so before installing it check that you have at

          least the ``openldap`` and ``sasl`` libraries.

LDAP settings are located in the Admin->LDAP section.

If your user groups are placed in an Organisation Unit (OU) structure, the Search Settings configuration differs::

to define a regular expression that will fetch an issue id stored in a commit

messages and replace that with a URL to the issue. To enable this simply

uncomment the following variables in the ini file::

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

The default expression matches issues in the format ``#<number>``, e.g., ``#300``.

Matched issues are replaced with the link specified as

``issue_server_link`` ``{id}`` is replaced with issue id, and

``{repo}`` with the repository name.  Since the # is stripped away,

``issue_prefix`` is prepended to the link text.  ``issue_prefix`` doesn't

necessarily need to be ``#``: if you set issue prefix to ``ISSUE-`` this will

generate a URL in the format::

Hooks can be managed in similar way to that used in ``.hgrc`` files.

To access hooks setting click `advanced setup` in the `Hooks` section

of Mercurial Settings in Admin.

There are four built in hooks that cannot be changed (only enabled/disabled by

checkboxes in the previous section).

To add another custom hook simply fill in the first section with

``<name>.<hook_type>`` and the second one with hook path. Example hooks

can be found in ``kallithea.lib.hooks``.

This is configurable as ``default_encoding`` in the .ini file.

encoding of commit messages. In addition Kallithea can detect if the ``chardet``

library is installed. If ``chardet`` is detected Kallithea will fallback to it