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

Kallithea README

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

About

-----

**Kallithea** is a fast and powerful management tool for Mercurial_ and Git_

with a built-in push/pull server, full text search and code-review. It works on

http/https and has a built in permission/authentication system with the ability

Kallithea was forked from RhodeCode in July 2014 and has been heavily modified.

Installation

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

Kallithea requires Python_ 2.x and it is recommended to install it in a

virtualenv_. Official releases of Kallithea can be installed with::

    pip install kallithea

The development repository is kept very stable and used in production by the

.. _api:

===

API

===

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

OUTPUT::

    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.

    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.

OUTPUT::

    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.

                 "locked_since": "<float lock_time>",

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

                                ...

                             ]

             }

    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.

                    "repositories": {"repo1": "repository.none"},

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

    error:  null

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.

                "ldap_dn" :  "<ldap_dn>",

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

    result: {

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

                              },

                              …

                            ]

             }

    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.

               "active":          "<bool>",

               },

               …

              ]

    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.

                     "group_name" :     "<groupname>",

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

              "success": True|False # depends on if member is in group

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

              "success":  True|False,  # depends on if member is in group

              "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,

                                  },

                                  …

                 ]

            }

    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.

                "enable_statistics": "<bool>",

              },

              …

            ]

    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.

                "type" :        "<type>",

              },

              …

            ]

    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

                "enable_locking":    "<bool>",

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

                "locked_by": "<username>",

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

    result: {

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

    result: {

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

    result: {

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

    result: {

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

    result: {

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

=========

Changelog

=========

Kallithea project doesn't keep its changelog here.  We refer you to our `Mercurial logs`__.

.. __: https://kallithea-scm.org/repos/kallithea/changelog

We use Weblate_ to translate the user interface messages into languages other

than English. Join our project on `Hosted Weblate`_ to help us.

To register, you can use your Bitbucket or GitHub account. See :ref:`translations`

for more details.

Getting started

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

To get started with development::

        hg clone https://kallithea-scm.org/repos/kallithea

    -x, --stop            Stop running tests after the first error or failure

    -s, --nocapture       Don't capture stdout (any stdout output will be

                          printed immediately) [NOSE_NOCAPTURE]

    --failed              Run the tests that failed in the last test run.

Coding/contribution guidelines

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

Kallithea is GPLv3 and we assume all contributions are made by the

committer/contributor and under GPLv3 unless explicitly stated. We do care a

lot about preservation of copyright and license information for existing code

that it can be (and is) used in production. Experimental changes should live

elsewhere (for example in a pull request) until they are ready.

.. _translations:

.. include:: ./../kallithea/i18n/how_to

"Roadmap"

---------

We do not have a road map but are waiting for your contributions. Refer to the

wiki_ for some ideas of places we might want to go -- contributions in these

areas are very welcome.

.. _index:

#######################

Kallithea Documentation

#######################

**Readme**

.. toctree::

   :maxdepth: 1

   readme

Other topics

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

* :ref:`genindex`

* :ref:`search`

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

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

.. _django: http://www.djangoproject.com/

.. _mercurial: http://mercurial.selenic.com/

.. _bitbucket: http://bitbucket.org/

.. _subversion: http://subversion.tigris.org/

  result, removing it is not as straightforward as with a virtualenv, as you'd

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

  needed by other packages.

.. _installation-source:

Installation from repository source

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

To install Kallithea in a virtualenv_ using the stable branch of the development

repository, follow the instructions below::

To upgrade, simply update the repository with ``hg pull -u`` and restart the

server.

.. _installation-virtualenv:

Installing a released version in a virtualenv

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

It is highly recommended to use a separate virtualenv_ for installing Kallithea.

This way, all libraries required by Kallithea will be installed separately from your

main Python installation and other applications and things will be less

  python libraries into the activated virtualenv.

You can now proceed to :ref:`setup`.

.. _installation-without-virtualenv:

Installing a released version without virtualenv

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

For installation without virtualenv, 'just' use::

    pip install kallithea

To install as a regular user in ``~/.local``, you can use::

    pip install --user kallithea

You can now proceed to :ref:`setup`.

Upgrading Kallithea from Python Package Index (PyPI)

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

.. note::

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

   configuration backup before doing an upgrade.

.. note::

    For the best security, it is strongly recommended to only host the site over

    a secure connection, e.g. using TLS.

Prerequisites

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

Apart from the normal requirements for Kallithea, it is also necessary to get an

ISAPI-WSGI bridge module, e.g. isapi-wsgi.

Installation

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

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.

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

user database with an external tool, or set it to *Automatic activation of

external account*. Finally, save the changes.

The last necessary step is to enable the relevant authentication in IIS, e.g.

Windows authentication.

Troubleshooting

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

Typically, any issues in this setup will either be entirely in IIS or entirely

in Kallithea (or Kallithea's WSGI/paster middleware). Consequently, two

different options for finding issues exist: IIS' failed request tracking which

.. _installation_win:

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

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.

- Disable UAC or run the installer with admin privileges. If you chose to disable UAC, do not forget to reboot afterwards.

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.

  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/

  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)

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

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

  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

  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.

Virtualenv will now be inside your Python Scripts path (C:\\Python27\\Scripts or similar).

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.

  pip install kallithea

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

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

If you make a mistake and the script doesn't end, don't worry: start it again.

If you decided not to install git, you will get errors about it that you can ignore.

Step 10 - Running Kallithea

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

In the previous command prompt, being in the C:\\Kallithea\\Bin folder, type::

  paster serve production.ini

.. _installation_win_old:

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

Installation and upgrade on Windows (XP/Vista/Server 2003/Server 2008)

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

First-time install

::::::::::::::::::

Target OS: Windows XP SP3 32-bit English (Clean installation)

+ All Windows Updates until 24-may-2012

   - http://blog.victorjabur.com/2011/06/05/compiling-python-2-7-modules-on-windows-32-and-64-using-msvc-2008-express/

   - http://bugs.python.org/issue7511

Step 1 - Install Visual Studio 2008 Express

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

Optional: You can also install MinGW, but VS2008 installation is easier.

Download "Visual C++ 2008 Express Edition with SP1" from:

http://download.microsoft.com/download/E/8/E/E8EEB394-7F42-4963-A2D8-29559B738298/VS2008ExpressWithSP1ENUX1504728.iso

(if not found or relocated, google for "visual studio 2008 express" for updated link. This link was taken from http://stackoverflow.com/questions/15318560/visual-c-2008-express-download-link-dead)

.. note::

   64-bit: You also need to copy and rename a .bat file to make the Visual C++ compiler work.

   I am not sure why this is not necessary for 32-bit.

   Copy C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars64.bat to C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\amd64\vcvarsamd64.bat

Step 2 -- Install Python

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

Install Python 2.x.y (x = 6 or 7) x86 version (32-bit). DO NOT USE A 3.x version.

Download Python 2.x.y from:

http://www.python.org/download/

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

.. note::

   64-bit: Just download and install the 64-bit version of python.

Step 3 -- Install Win32py extensions

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

Download pywin32 from:

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

  .. note::

     64-bit: Download and install the 64-bit version.

     At the time of writing you can find this at:

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

Step 4 -- Python BIN

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

Add Python BIN folder to the path

You have to add the Python folder to the path, you can do it manually

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

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

  Typically: C:\\Python27

Step 5 -- Kallithea folder structure

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

Create a Kallithea folder structure

This is only a example to install Kallithea, you can of course change

  C:\Kallithea

  C:\Kallithea\Bin

  C:\Kallithea\Env

  C:\Kallithea\Repos

Step 6 -- Install virtualenv

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

Install Virtual Env for Python

Navigate to: http://www.virtualenv.org/en/latest/index.html#installation

 python virtualenv.py C:\Kallithea\Env

(--no-site-packages is now the default behaviour of virtualenv, no need

to include it)

Step 7 -- Install Kallithea

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

Finally, install Kallithea

Close previously opened command prompt/s, and open a Visual Studio 2008

 pip install kallithea

(long step, please wait until fully complete)

Some warnings will appear, don't worry as they are normal.

Step 8 -- Configuring Kallithea

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

steps taken from http://packages.python.org/Kallithea/setup.html

You have to use the same Visual Studio 2008 command prompt as Step7, so

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

whatever you want)

If you make some mistake and the script does not end, don't worry, start

it again.

Step 9 -- Running Kallithea

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

In the previous command prompt, being in the C:\\Kallithea\\Bin folder,

just type::

 paster serve production.ini

Open yout web server, and go to http://127.0.0.1:5000

Remark:

If it does not work first time, just Ctrl-C the CMD process and start it

again. Don't forget the "http://" in Internet Explorer

What this Guide does not cover:

- Installing Celery