works on Unix-like systems and Windows, and is powered by the vcs_ library

created by Łukasz Balcerzak and Marcin Kuźmiński to uniformly handle multiple

version control systems.

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

Please visit https://docs.kallithea-scm.org/en/latest/installation.html for

more details.

Source code

Community

---------

**Kallithea** is maintained by its users who contribute the fixes they would

Get in touch with the rest of the community:

  http://lists.sfconservancy.org/mailman/listinfo/kallithea-general.

- Use IRC and join #kallithea on FreeNode (irc.freenode.net) or use

  http://webchat.freenode.net/?channels=kallithea.

- Follow Kallithea on Twitter, **@KallitheaSCM**.

.. Note::

   If you started out using the branding interoperability approach mentioned

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

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

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

.. _Sphinx: http://sphinx.pocoo.org/

.. _Mercurial: http://mercurial.selenic.com/

.. _Bitbucket: http://bitbucket.org/

.. _GitHub: http://github.com/

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

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

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

that should have API access enabled.

    api_access_controllers_whitelist =

        ChangesetController:changeset_patch,

        ChangesetController:changeset_raw,

        FilesController:raw,

        FilesController:archivefile

After this change, a Kallithea view can be accessed without login by adding a

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

Exposing raw diffs is a good way to integrate with

API access

++++++++++

Clients must send JSON encoded JSON-RPC requests::

        "method": "<method_name>",

        "args": {"<arg_key>": "<arg_val>"}

    }

For example, to pull to a local "CPython" mirror using curl::

In general, provide

 - *id*, a value of any type, can be used to match the response with the request that it is replying to.

 - *api_key*, for authentication and permission validation.

 - *args*, the arguments to pass to the method.

.. note::

The response to the JSON-RPC API call will always be a JSON structure::

    {

    }

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

*result* will be null.

API client

++++++++++

way to call the JSON-RPC API.

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

 kallithea-api --apihost=<your.kallithea.server.url> --apikey=<yourapikey> get_repo

     'result': <json data...>}

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

  kallithea-api --save-config --apihost=<your.kallithea.server.url> --apikey=<yourapikey>

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

API methods

+++++++++++

              },

              …

            ]

    error:  null

create_user

-----------

Create new user.

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

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.

.. _changelog:

=========

Changelog

=========

# If true, sectionauthor and moduleauthor directives will be shown in the

# output. They are ignored by default.

#show_authors = False

# The name of the Pygments (syntax highlighting) style to use.

pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.

#modindex_common_prefix = []

# -- Options for HTML output ---------------------------------------------------

your own itch.

Infrastructure

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

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.

Running tests

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

After finishing your changes make sure all tests pass cleanly. You can run

the testsuite running ``nosetests`` from the project root, or if you use tox

When running tests, Kallithea uses `kallithea/tests/test.ini` and populates the

SQLite database specified there.

It is possible to avoid recreating the full test database on each invocation of

the tests, thus eliminating the initial delay. To achieve this, run the tests as::

We try to support the most common modern web browsers. IE9 is still supported

to the extent it is feasible, IE8 is not.

We primarily support Linux and OS X on the server side but Windows should also work.

should use templates cleverly and avoid duplication. We should use reasonable

We should only use inline styles in places where it really is semantic (such as

Commit messages should have a leading short line summarizing the changes. For

bitbucket, something hosted on your own Kallithea instance, or patches sent by

Make sure to test your changes both manually and with the automatic tests

before posting.

We care about quality and review and keeping a clean repository history. We

might give feedback that requests polishing contributions until they are

"perfect". We might also rebase and collapse and make minor adjustments to your

changes when we apply them.

We try to make sure we have consensus on the direction the project is taking.

mailing list.  We aim at having all non-trivial changes reviewed by at least

one other core developer before pushing. Obvious non-controversial changes will

be handled more casually.

For now we just have one official branch ("default") and will keep it so stable

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

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

"Roadmap"

---------

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

areas are very welcome.

Thank you for your contribution!

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

.. _Weblate: http://weblate.org/

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

.. _mailing list: http://lists.sfconservancy.org/mailman/listinfo/kallithea-general

.. _Hosted Weblate: https://hosted.weblate.org/projects/kallithea/kallithea/

.. _wiki: https://bitbucket.org/conservancy/kallithea/wiki/Home

.. _installation:

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

Installation on Unix/Linux

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

- :ref:`installation-source`: The simplest way to keep the installation

- :ref:`installation-virtualenv`: If you prefer to only use released versions

  of Kallithea, the recommended method is to install Kallithea in a virtual

  Python environment using `virtualenv`. The advantages of this method over

  direct installation is that Kallithea and its dependencies are completely

  contained inside the virtualenv (which also means you can have multiple

.. _installation-source:

Installation from repository source

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

repository, follow the instructions below::

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

        cd kallithea

        virtualenv ../kallithea-venv

        source ../kallithea-venv/bin/activate

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

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

Installation

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

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

.. note::

ISAPI handler

.............

The ISAPI handler can be generated using::

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

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

First-time install

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

+ All Windows Updates until 24-may-2012

.. note::

   plus some extra tweaks.

   Tested on Windows Server 2008 R2 SP1, 9-feb-2013.

   - 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

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

   Silverlight Runtime and SQL Server 2008 Express Edition are not

   required, you can uncheck them

.. note::

   Download from: http://www.microsoft.com/en-us/download/details.aspx?id=3138

.. note::

   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

Download Python 2.x.y from:

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

Installer". While writing this guide, the latest version was v2.7.3.

Remember the specific major and minor version installed, because it will

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

.. note::

Download pywin32 from:

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

- Click on "pywin32" folder

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

  version of Python you installed (in this case, 7)

  When writing this guide, the file was:

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

  .. note::

     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

Add Python BIN folder to the path

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

(editing "PATH" environment variable) or using Windows Support Tools

that came preinstalled in Vista/7 and can be installed in Windows XP.

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

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

  Typically: C:\\Python27

Create a Kallithea folder structure

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

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

later adapt the paths if you change them. My recommendation is to use

  C:\Kallithea

  C:\Kallithea\Bin

  C:\Kallithea\Env

  C:\Kallithea\Repos

Install Virtual Env for Python

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

Right click on "virtualenv.py" file and choose "Save link as...".

Download to C:\\Kallithea (or whatever you want)

 python virtualenv.py C:\Kallithea\Env

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

to include it)

Finally, install Kallithea

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

Command Prompt (**IMPORTANT!!**). To do so, go to Start Menu, and then open

"Microsoft Visual C++ 2008 Express Edition" -> "Visual Studio Tools" ->

"Visual Studio 2008 Command Prompt"

.. note::

   Visual Studio 2008 Command Prompt. Use right-mouse click to open properties.

Change commandline from::

%comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" x86

(long step, please wait until fully complete)

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

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

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

if you closed it reopen it following the same commands (including the

"activate" one). When ready, just type::

whatever you want)

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

it again.

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

just type::

 paster serve production.ini

First, you will need to create a Kallithea configuration file. Run the

following command to do so::

    paster make-config Kallithea my.ini

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

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

settings, and logging.

Next, you need to create the databases used by Kallithea. It is recommended to

use PostgreSQL or SQLite (default). If you choose a database other than the

This will prompt you for a "root" path. This "root" path is the location where

Kallithea will store all of its repositories on the current machine. After

entering this "root" path ``setup-db`` will also prompt you for a username

and password for the initial admin account which ``setup-db`` sets

up for you.

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

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

    paster serve my.ini

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

- The default permissions on each repository is read, and the owner is admin.

  Remember to update these if needed.

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

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

Extensions

----------

    paster make-rcext my.ini

This will create an ``rcextensions`` package next to the specified ``ini`` file.

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

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

          to the Kallithea db and run check functions for permissions

          against that.

Setting up Whoosh full text search

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

    paster make-index my.ini

    paster make-index my.ini -f

    paster make-index my.ini --index-only=vcs,kallithea

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,

Setting up LDAP support

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

Kallithea supports LDAP authentication. In order

to use LDAP, you have to install the python-ldap_ package. This package is

    pip install python-ldap

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

Kallithea supports delegating the authentication

of users to its WSGI container, or to a reverse-proxy server through which all

clients access the application.

When these authentication methods are enabled in Kallithea, it uses the

perform the authentication itself. The authorization, however, is still done by

Kallithea according to its settings.

When a user logs in for the first time using these authentication methods,

a matching user account is created in Kallithea with default permissions. An

administrator can then modify it using Kallithea's admin interface.

It's also possible for an administrator to create accounts and configure their

Container-based authentication

''''''''''''''''''''''''''''''

In a container-based authentication setup, Kallithea reads the user name from

the ``REMOTE_USER`` server variable provided by the WSGI container.

to configure it to require authentication on the location configured for

Kallithea.

Proxy pass-through authentication

'''''''''''''''''''''''''''''''''

In a proxy pass-through authentication setup, Kallithea reads the user name

from the ``X-Forwarded-User`` request header, which should be configured to be

sent by the reverse-proxy server.

After setting up your proxy solution (see `Apache virtual host reverse proxy example`_,

configure the authentication and add the username in a request header named

``X-Forwarded-User``.

For example, the following config section for Apache sets a subdirectory in a

      SetEnvIf X-Url-Scheme https HTTPS=1

      AuthType Basic

      AuthName "Kallithea authentication"

      AuthUserFile /srv/kallithea/.htpasswd