}

    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.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_user"

    args :    {

                "userid" : "<username or user_id Optional(=apiuser)>"

              }

OUTPUT::

    id : <id_given_in_input>

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

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_users"

    args :    { }

OUTPUT::

    id : <id_given_in_input>

    result: [

              {

                "email" :       "<email>",

                "emails":       "<list_of_all_additional_emails>",

                "ip_addresses": "<list_of_ip_addresses_for_user>",

                "active" :      "<bool>",

                "admin" :       "<bool>",

                "ldap_dn" :     "<ldap_dn>",

                "last_login":   "<last_login>",

              },

              …

            ]

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

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "create_user"

    args :    {

                "username" :  "<username>",

                "email" :     "<useremail>",

                "password" :  "<password = Optional(None)>",

                "firstname" : "<firstname> = Optional(None)",

                "lastname" :  "<lastname> = Optional(None)",

                "active" :    "<bool> = Optional(True)",

    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.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "update_user"

    args :    {

                "userid" : "<user_id or username>",

                "username" :  "<username> = Optional(None)",

                "email" :     "<useremail> = Optional(None)",

                "password" :  "<password> = Optional(None)",

                "firstname" : "<firstname> = Optional(None)",

                "lastname" :  "<lastname> = Optional(None)",

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

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "delete_user"

    args :    {

                "userid" : "<user_id or username>",

              }

OUTPUT::

    id : <id_given_in_input>

    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.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_user_group"

    args :    {

                "usergroupid" : "<user group id or name>"

              }

OUTPUT::

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

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_user_groups"

    args :    { }

OUTPUT::

    id : <id_given_in_input>

    result : [

               {

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

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "create_user_group"

    args:     {

                "group_name": "<groupname>",

                "owner" :     "<owner_name_or_id = Optional(=apiuser)>",

                "active":     "<bool> = Optional(True)"

              }

OUTPUT::

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

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "add_user_user_group"

    args:     {

                "usersgroupid" : "<user group id or name>",

                "userid" : "<user_id or username>",

              }

OUTPUT::

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

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "remove_user_from_user_group"

    args:     {

                "usersgroupid" : "<user group id or name>",

                "userid" : "<user_id or username>",

              }

OUTPUT::

                                  …

                 ]

            }

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

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_repos"

    args:     { }

OUTPUT::

    id : <id_given_in_input>

    result: [

              {

              },

              …

            ]

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

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "get_repo_nodes"

    args:     {

                "repoid" : "<reponame or repo_id>"

                "revision"  : "<revision>",

                "root_path" : "<root_path>",

                "ret_type"  : "<ret_type> = Optional('all')"

              }

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,

or that of a regular user with create repository permission.

Regular users cannot specify owner parameter.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "create_repo"

    args:     {

                "repo_name" :        "<reponame>",

                "owner" :            "<owner_name_or_id = Optional(=apiuser)>",

                "repo_type" :        "<repo_type> = Optional('hg')",

                "description" :      "<description> = Optional('')",

                "private" :          "<bool> = Optional(False)",

                "clone_uri" :        "<clone_uri> = Optional(None)",

              },

            }

    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.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "update_repo"

    args:     {

                "repoid" :           "<reponame or repo_id>"

                "name" :             "<reponame> = Optional('')",

                "group" :            "<group_id> = Optional(None)",

                "owner" :            "<owner_name_or_id = Optional(=apiuser)>",

                "description" :      "<description> = Optional('')",

                "private" :          "<bool> = Optional(False)",

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

repository permission and at least read access to the repository.

Regular users cannot specify owner parameter.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "fork_repo"

    args:     {

                "repoid" :          "<reponame or repo_id>",

                "fork_name":        "<forkname>",

                "owner":            "<username or user_id = Optional(=apiuser)>",

                "description":      "<description>",

                "copy_permissions": "<bool>",

                "private":          "<bool>",

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

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "delete_repo"

    args:     {

                "repoid" : "<reponame or repo_id>",

                "forks"  : "`delete` or `detach` = Optional(None)"

              }

OUTPUT::

    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.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "grant_user_permission"

    args:     {

                "repoid" : "<reponame or repo_id>"

                "userid" : "<username or user_id>"

                "perm" :       "(repository.(none|read|write|admin))",

              }

OUTPUT::

    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.

INPUT::

    id : <id_for_response>

    api_key : "<api_key>"

    method  : "revoke_user_permission"

    args:     {

                "repoid" : "<reponame or repo_id>"

                "userid" : "<username or user_id>"

              }

OUTPUT::

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

    id : <id_for_response>

    api_key : "<api_key>"

    method :  "grant_user_group_permission"

    args:     {

                "repoid" : "<reponame or repo_id>"

                "usersgroupid" : "<user group id or name>"

                "perm" : "(repository.(none|read|write|admin))",

              }

OUTPUT::

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.

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

   Kallithea that these files were used with.  If backing up your Kallithea

   instance from version 0.1 to 0.2, the ``my.ini`` file could be

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

If using a SQLite database, stop the Kallithea process/daemon/service, and

then make a copy of the database file::

 service kallithea stop

 cp kallithea.db kallithea.db.{version}

Back up your configuration file::

 cp my.ini my.ini.{version}

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

installed Kallithea in by running::

 pip freeze

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

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

 source /srv/kallithea/venv/bin/activate

Once you have verified the environment you can upgrade Kallithea with::

 pip install --upgrade kallithea

Then run the following command from the installation directory::

 paster make-config Kallithea my.ini

This will display any changes made by the new version of Kallithea to your

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

that you recheck the content after the automerge.

.. note::

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

   often be caused by missing parameters added in new versions.

It is also recommended that you rebuild the whoosh index after upgrading since

the new whoosh version could introduce some incompatible index changes. Please

read the changelog to see if there were any changes to whoosh.

The final step is to upgrade the database. To do this simply run::

 paster upgrade-db my.ini

This will upgrade the schema and update some of the defaults in the database,

and will always recheck the settings of the application, if there are no new

options that need to be set.

.. note::

   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

   You can always specify what version of Kallithea you want to install for example in pip

   `pip install Kallithea==0.2`

You may find it helpful to clear out your log file so that new errors are

readily apparent::

 echo > kallithea.log

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

  paster serve production.ini

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

It works!! :-)

Remark:

If it does not work the first time, 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

- Running Kallithea as a Windows Service. You can investigate here:

  - http://pypi.python.org/pypi/wsgisvc

  - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/

  - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service

- Using Apache. You can investigate here:

  - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4

   64-bit: For 64-bit you need to modify the shortcut that is used to start the

   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

to::

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

In that CMD (loaded with VS2008 PATHs) type::

  cd C:\Kallithea\Env\Scripts (or similar)

  activate

The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar

(depending of your folder structure). Then type::

 pip install kallithea

(long step, please wait until fully complete)

just type::

 paster serve production.ini

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

It works!! :-)

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

- Running Kallithea as Windows Service. You can investigate here:

  - http://pypi.python.org/pypi/wsgisvc

  - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/

  - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service

- Using Apache. You can investigate here:

  - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4

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

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

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

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

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

configuration file to use this other database. Kallithea currently supports

PostgreSQL, SQLite and MySQL databases. Create the database by running

the following command::

    paster setup-db my.ini

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.

The ``setup-db`` values can also be given on the command line.

Example::

    paster setup-db my.ini --user=nn --password=secret --email=nn@example.org --repos=/srv/repos

The ``setup-db`` command will create all 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

For a full index rebuild, run::

    paster make-index my.ini -f

The ``--repo-location`` option allows the location of the repositories to be overriden;

usually, the location is retrieved from the Kallithea database.

The ``--index-only`` option can be used to limit the indexed repositories to a comma-separated list::

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

To keep your index up-to-date it is necessary to do periodic index builds;

for this, it is recommended to use a crontab entry. Example::

    0  3  *  *  *  /path/to/virtualenv/bin/paster make-index /path/to/kallithea/my.ini

When using incremental mode (the default), Whoosh will check the last

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,

or in the admin panel you can check the "build from scratch" checkbox.

      AuthName "Kallithea authentication"

      AuthUserFile /srv/kallithea/.htpasswd

      Require valid-user

      RequestHeader unset X-Forwarded-User

      RewriteEngine On

      RewriteCond %{LA-U:REMOTE_USER} (.+)

      RewriteRule .* - [E=RU:%1]

      RequestHeader set X-Forwarded-User %{RU}e

    </Location>

.. note::

   If you enable proxy pass-through authentication, make sure your server is

   only accessible through the proxy. Otherwise, any client would be able to

   forge the authentication header and could effectively become authenticated

   using any account of their liking.

Integration with issue trackers

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

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

to define a regular expression that will match an issue ID in commit messages,

  use_celery = true

and add or change the ``celery.*`` and ``broker.*`` configuration variables.

Remember that the ini files use the format with '.' and not with '_' like

Celery. So for example setting `BROKER_HOST` in Celery means setting

`broker.host` in the configuration file.

To start the Celery process, run::

 paster celeryd <configfile.ini>

.. note::

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

   user that Kallithea runs.

HTTPS support

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

Kallithea will by default generate URLs based on the WSGI environment.

Alternatively, you can use some special configuration settings to control

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

            #important !

            #Directive to properly generate url (clone url) for pylons

            ProxyPreserveHost On

            #kallithea instance

            ProxyPass / http://127.0.0.1:5000/

            ProxyPassReverse / http://127.0.0.1:5000/

            #to enable https use line below

            #SetEnvIf X-Url-Scheme https HTTPS=1

    </VirtualHost>

Additional tutorial

http://pylonsbook.com/en/1.1/deployment.html#using-apache-to-proxy-requests-to-pylons

Apache as subdirectory

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

Apache subdirectory part:

.. code-block:: apache

    <Location /<someprefix> >

    a2enmod wsgi

- Create a wsgi dispatch script, like the one below. Make sure you

  check that the paths correctly point to where you installed Kallithea

  and its Python Virtual Environment.

- Enable the ``WSGIScriptAlias`` directive for the WSGI dispatch script,

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

  correctly specified.

Here is a sample excerpt from an Apache Virtual Host configuration file:

.. code-block:: apache

    WSGIDaemonProcess kallithea \

        processes=1 threads=4 \

        python-path=/srv/kallithea/pyenv/lib/python2.7/site-packages

    WSGIScriptAlias / /srv/kallithea/dispatch.wsgi

    WSGIPassAuthorization On

Or if using a dispatcher WSGI script with proper virtualenv activation:

.. code-block:: apache

Cloning remote repositories

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

Kallithea has the ability to clone repositories from given remote locations.

Currently it supports the following options:

- hg  -> hg clone

- svn -> hg clone

- git -> git clone

.. note:: svn -> hg cloning requires the ``hgsubversion`` library to be

   installed.

If you need to clone repositories that are protected via basic authentication,

you can pass the credentials in the URL, e.g.

``http://user:passw@remote.server/repo``. Kallithea will then try to login and

clone using the given credentials. Please note that the given credentials will

be stored as plaintext inside the database. However, the authentication

information will not be shown in the clone URL on the summary page.

Specific features configurable in the Admin settings