database:

- keep the database unconverted (intended for testing and evaluation)

- convert the database in a one-time step

Maintaining interoperability

Interoperability with RhodeCode 2.2.X installations is provided so you don't

have to immediately commit to switching to Kallithea. This option will most

likely go away once the two projects have diverged significantly.

To run Kallithea on a RhodeCode database, run::

   python2 setup.py install

then you will find this location at

``$VIRTUAL_ENV/lib/python2.7/site-packages/Kallithea-0.1-py2.7.egg/kallithea``.

One-time conversion

Alternatively, if you would like to convert the database for good, you can use

a helper script provided by Kallithea. This script will operate directly on the

database, using the database string you can find in your ``production.ini`` (or

``development.ini``) file. For example, if using SQLite::

.. Note::

   If you started out using the branding interoperability approach mentioned

   above, watch out for stray brand.pyc after removing brand.py.

Git hooks

After switching to Kallithea, it will be necessary to update the Git_ hooks in

your repositories. If not, the Git_ hooks from RhodeCode will still be called,

which will cause ``git push`` to fail every time.

If you do not have any custom Git_ hooks deployed, perform the following steps

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

methods. Everything is available by sending JSON encoded http(s) requests to

``<your_server>/_admin/api``.

API access for web views

API access can also be turned on for each web view in Kallithea that is

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

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

RSS/Atom feed views are enabled. Other views are

only available if they have been whitelisted. Edit the

Exposing raw diffs is a good way to integrate with

third-party services like code review, or build farms that can download archives.

API access

Clients must send JSON encoded JSON-RPC requests::

    {

        "id: "<id>",

        "api_key": "<api_key>",

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

the reponse will have a failure description in *error* and

*result* will be null.

API client

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

way to call the JSON-RPC API.

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

This will create a ``~/.config/kallithea`` with the specified URL and API key

so you don't have to specify them every time.

API methods

pull

Pull the given repo from remote location. Can be used to automatically keep

remote repos up to date.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

    id : <id_given_in_input>

    result : "Pulled from `<reponame>`"

    error :  null

rescan_repos

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

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

This command can only be executed using the api_key of a user with admin rights.

INPUT::

    id : <id_given_in_input>

    result : "{'added': [<list of names of added repos>],

               'removed': [<list of names of removed repos>]}"

    error :  null

invalidate_cache

Invalidate the cache for a repository.

This command can only be executed using the api_key of a user with admin rights,

or that of a regular user with admin or write access to the repository.

INPUT::

    id : <id_given_in_input>

    result : "Caches of repository `<reponame>`"

    error :  null

lock

Set the locking state on the given repository by the given user.

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.

This command can only be executed using the api_key of a user with admin rights, or that of a regular user with admin or write access to the repository.

                 "locked_by": "<username>",

                 "msg": "User `<username>` set lock state for repo `<reponame>` to `<false|true>`"

             }

    error :  null

get_ip

Return IP address as seen from Kallithea server, together with all

defined IP addresses for given user.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

                             ]

             }

    error :  null

get_user

Get a user by username or userid. The result is empty if user can't be found.

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

Any userid can be specified when the command is executed using the api_key of a user with admin rights.

Regular users can only speicy their own userid.

                    "repositories_groups": {"Group1": "group.read"}

                 },

            }

    error:  null

get_users

List all existing users.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

            ]

    error:  null

.. _create-user:

create_user

Create new user.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

Example::

    kallithea-api create_user username:bent email:bent@example.com firstname:Bent lastname:Bentsen extern_type:ldap extern_name:uid=bent,dc=example,dc=com

update_user

Update the given user if such user exists.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

                "last_login": "<last_login>",

              },

            }

    error:  null

delete_user

Delete the given user if such a user exists.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

              "msg" : "deleted user ID:<userid> <username>",

              "user": null

            }

    error:  null

get_user_group

Get an existing user group.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

                              …

                            ]

             }

    error : null

get_user_groups

List all existing user groups.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

               },

               …

              ]

    error : null

create_user_group

Create a new user group.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

                     "active":          "<bool>",

               },

            }

    error:  null

add_user_to_user_group

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

``false``.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

              "msg": "added member `<username>` to a user group `<groupname>` |

                      User is already in that group"

            }

    error:  null

remove_user_from_user_group

Remove a user from a user group. If the user isn't in the given group, success will

be ``false``.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

              "msg": "removed member <username> from user group <groupname> |

                      User wasn't in group"

            }

    error:  null

get_repo

Get an existing repository by its name or repository_id. Members will contain

either users_group or users associated to that repository.

This command can only be executed using the api_key of a user with admin rights,

or that of a regular user with at least read access to the repository.

                                  …

                 ]

            }

    error:  null

get_repos

List all existing repositories.

This command can only be executed using the api_key of a user with admin rights,

or that of a regular user with at least read access to the repository.

INPUT::

              },

              …

            ]

    error:  null

get_repo_nodes

Return a list of files and directories for a given path at the given revision.

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

This command can only be executed using the api_key of a user with admin rights.

INPUT::

              },

              …

            ]

    error:  null

create_repo

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

groups will be created. For example "foo/bar/baz" will create repository groups

"foo", "bar" (with "foo" as parent), and create "baz" repository with

"bar" as group.

This command can only be executed using the api_key of a user with admin rights,

                "enable_statistics": "<bool>",

              },

            }

    error:  null

update_repo

Update a repository.

This command can only be executed using the api_key of a user with admin rights,

or that of a regular user with create repository permission.

Regular users cannot specify owner parameter.

                "locked_date": "<float lock_time>",

              },

            }

    error:  null

fork_repo

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

return success message immediately and a fork will be created

asynchronously.

This command can only be executed using the api_key of a user with admin

rights, or with the global fork permission, by a regular user with create

              "msg": "Created fork of `<reponame>` as `<forkname>`",

              "success": true

            }

    error:  null

delete_repo

Delete a repository.

This command can only be executed using the api_key of a user with admin rights,

or that of a regular user with admin access to the repository.

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

              "msg": "Deleted repository `<reponame>`",

              "success": true

            }

    error:  null

grant_user_permission

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

This command can only be executed using the api_key of a user with admin rights.

INPUT::

              "msg" : "Granted perm: `<perm>` for user: `<username>` in repo: `<reponame>`",

              "success": true

            }

    error:  null

revoke_user_permission

Revoke permission for a user on the given repository.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

              "msg" : "Revoked perm for user: `<username>` in repo: `<reponame>`",

              "success": true

            }

    error:  null

grant_user_group_permission

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

existing one if found.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

              "msg" : "Granted perm: `<perm>` for group: `<usersgroupname>` in repo: `<reponame>`",

              "success": true

            }

    error:  null

revoke_user_group_permission

Revoke permission for a user group on the given repository.

This command can only be executed using the api_key of a user with admin rights.

INPUT::

   api/api

   api/models

Other topics

* :ref:`genindex`

* :ref:`search`

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

The following assumes that your Kallithea is at ``c:\inetpub\kallithea``, and

will be served from the root of its own website. The changes to serve it in its

own virtual folder will be noted where appropriate.

Application pool

Make sure that there is a unique application pool for the Kallithea application

with an identity that has read access to the Kallithea distribution.

The application pool does not need to be able to run any managed code. If you

are using a 32-bit Python installation, then you must enable 32-bit program in

.. note::

    The application pool can be the same as an existing application pool,

    as long as the Kallithea requirements are met by the existing pool.

ISAPI handler

The ISAPI handler can be generated using::

    paster install-iis my.ini --root=/

This will generate a ``dispatch.py`` file in the current directory that contains

be the one handling all requests to the specified root. When the website starts

the ISAPI handler, it will start a thread pool managed wrapper around the paster

middleware WSGI handler that Kallithea runs within and each HTTP request to the

site will be processed through this logic henceforth.

Authentication with Kallithea using IIS authentication modules

The recommended way to handle authentication with Kallithea using IIS is to let

IIS handle all the authentication and just pass it to Kallithea.

To move responsibility into IIS from Kallithea, we need to configure Kallithea

to let external systems handle authentication and then let Kallithea create the

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

Installation and upgrade on Windows (7/Server 2008 R2 and newer)

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

First time install

Target OS: Windows 7 and newer or Windows Server 2008 R2 and newer

Tested on Windows 8.1, Windows Server 2008 R2 and Windows Server 2012

To install on an older version of Windows, see `<installation_win_old.html>`_

Step 1 -- Install Python

Install Python 2.x.y (x = 6 or 7). Latest version is recommended. If you need another version, they can run side by side.

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

- Download Python 2.x.y from http://www.python.org/download/

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

Remember the specific major and minor versions installed, because they will

be needed in the next step. In this case, it is "2.7".

Step 2 -- Python BIN

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.

Open a CMD and type::

  SETX PATH "%PATH%;[your-python-path]" /M

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

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

Step 3 -- Install pywin32 extensions

Download pywin32 from:

http://sourceforge.net/projects/pywin32/files/

- Click on "pywin32" folder

- Click on the first folder (in this case, Build 219, maybe newer when you try)

  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)

Step 4 -- Install pip

pip is a package management system for Python. You will need it to install Kallithea and its dependencies.

If you installed Python 2.7.9+, you already have it (as long as you ran the installer with admin privileges or disabled UAC).

If it was not installed or if you are using Python>=2.6,<2.7.9:

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

open a CMD and type::

  SETX PATH "%PATH%;[your-python-path]\Scripts" /M

Step 5 -- Kallithea folder structure

Create a Kallithea folder structure.

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

  C:\Kallithea

  C:\Kallithea\Bin

  C:\Kallithea\Env

  C:\Kallithea\Repos

Step 6 -- Install virtualenv

.. note::

   A python virtual environment will allow for isolation between the Python packages of your system and those used for Kallithea.

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

In a command prompt type::

To create a virtual environment, run::

  virtualenv C:\Kallithea\Env

Step 7 -- Install Kallithea

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.

Some Python packages use managed code and need to be compiled.

This can be done on Linux without any special steps. On Windows, you will need to install Microsoft Visual C++ compiler for Python 2.7.

Download and install "Microsoft Visual C++ Compiler for Python 2.7" from http://aka.ms/vcpython27

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

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

          normal.

Step 8 -- Install git (optional)

Mercurial being a python package, it was installed automatically when doing "pip install kallithea".

You need to install git manually if you want Kallithea to be able to host git repositories.

See http://git-scm.com/book/en/v2/Getting-Started-Installing-Git#Installing-on-Windows for instructions.

Step 9 -- Configuring Kallithea

Steps taken from `<setup.html>`_

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"