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

    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.

---------

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

   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/

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,

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

Exposing raw diffs is a good way to integrate with

API access

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 --save-config --apihost=<your.kallithea.server.url> --apikey=<yourapikey>

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

    error:  null

create_user

-----------

            }

    error:  null

update_user

-----------

Changelog

=========

# 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 = []

Infrastructure

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

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

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

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.

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.

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.

---------

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

areas are very welcome.

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

Installation from repository source

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

repository, follow the instructions below::

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

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.

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

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

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

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

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

  Typically: C:\\Python27

Create a Kallithea folder structure

  C:\Kallithea\Repos

Install Virtual Env for Python

to include it)

Finally, install Kallithea

.. note::

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

Change commandline from::

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

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

it again.

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

    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.

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

    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

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

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.

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

      RequestHeader unset X-Forwarded-User

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

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

uncomment the following variables in the ini file::

    issue_pat = (?:^#|\s#)(\w+)

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

``{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

  <a href="https://myissueserver.com/example_repo/issue/300">ISSUE-300</a>

    issue_prefix_wiki = WIKI-

With these settings, wiki pages can be referenced as wiki-some-id, and every

  <a href="https://mywiki.com/some-id">WIKI-some-id</a>

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

of Mercurial Settings in Admin.

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

   Make sure you run this command from the same virtualenv, and with the same

   user that Kallithea runs.

HTTPS support

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

Alternatively, you can use some special configuration settings to control

directly which scheme/protocol Kallithea will use when generating URLs:

- With ``force_https = true`` the default will be ``https``.

Nginx virtual host example

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

    upstream kallithea {

        server 127.0.0.1:5000;

Apache virtual host reverse proxy example

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

    <VirtualHost *:80>

            ServerName hg.myserver.com

            ServerAlias hg.myserver.com

            <Proxy *>

            </Proxy>

            #important !

            #to enable https use line below

            #SetEnvIf X-Url-Scheme https HTTPS=1

    </VirtualHost>

Apache as subdirectory

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

    <Location /<someprefix> >

      ProxyPass http://127.0.0.1:5000/<someprefix>

then change ``<someprefix>`` into your chosen prefix

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

Alternatively, Kallithea can be set up with Apache under mod_wsgi. For

  as in the following example. Once again, check the paths are

  correctly specified.

    WSGIDaemonProcess kallithea \

        processes=1 threads=4 \

    WSGIScriptAlias / /srv/kallithea/dispatch.wsgi

    WSGIPassAuthorization On

    WSGIDaemonProcess kallithea processes=1 threads=4

    WSGIScriptAlias / /srv/kallithea/dispatch.wsgi

   gets it's own cache invalidation key.

    import os

    os.environ["HGENCODING"] = "UTF-8"

    fileConfig('/srv/kallithea/my.ini')

    application = loadapp('config:/srv/kallithea/my.ini')

    activate_this = '/srv/kallithea/venv/bin/activate_this.py'

    import os

    os.environ['HOME'] = '/srv/kallithea'

Other configuration files

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