#email_to = admin@example.com another_admin@example.com

## 'From' header for error emails. You can optionally add a name.

## Default:

#error_email_from = pylons@yourapp.com

## Examples:

#error_email_from = Kallithea Errors <kallithea-noreply@example.com>

#error_email_from = paste_error@example.com

## SMTP server settings

## Only smtp_server is mandatory. All other settings take the specified default

## values.

#smtp_username =

#smtp_password =

#smtp_port = 25

#smtp_use_tls = false

#smtp_use_ssl = false

## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).

## If empty, use any of the authentication parameters supported by the server.

#smtp_auth =

[server:main]

## PASTE ##

#use = egg:Paste#http

## RSS feed options

rss_cut_off_limit = 256000

rss_items_per_page = 10

rss_include_diff = false

## options for showing and identifying changesets

show_sha_length = 12

show_revision_number = false

## gist URL alias, used to create nicer urls for gist. This should be an

## url that does rewrites to _admin/gists/<gistid>.

gist_alias_url =

## white list of API enabled controllers. This allows to add list of

## controllers to which access will be enabled by api_key. eg: to enable

## api access to raw_files put `FilesController:raw`, to enable access to patches

## add `ChangesetController:changeset_patch`. This list should be "," separated

## Syntax is <ControllerClass>:<function>. Check debug logs for generated names

## Recommended settings below are commented out:

api_access_controllers_whitelist =

#    ChangesetController:changeset_patch,

#    ChangesetController:changeset_raw,

#    FilesController:raw,

## comment out issue_pat, issue_server, issue_prefix to enable

## pattern to get the issues from commit messages

## default one used here is #<numbers> with a regex passive group for `#`

## {id} will be all groups matched from this pattern

issue_pat = (?:\s*#)(\d+)

## server url to the issue, each {id} will be replaced with match

## fetched from the regex and {repo} is replaced with full repository name

## including groups {repo_name} is replaced with just name of repo

## prefix to add to link to indicate it's an url

## #314 will be replaced by <issue_prefix><id>

issue_prefix = #

## issue_pat, issue_server_link, issue_prefix can have suffixes to specify

## multiple patterns, to other issues server, wiki or others

## below an example how to create a wiki pattern

#issue_pat_wiki = (?:wiki-)(.+)

#issue_prefix_wiki = WIKI-

## instance-id prefix

## a prefix key for this instance used for cache invalidation when running

## multiple instances of kallithea, make sure it's globally unique for

## all running kallithea instances. Leave empty if you don't use it

instance_id =

## alternative return HTTP header for failed authentication. Default HTTP

## response is 401 HTTPUnauthorized. Currently Mercurial clients have trouble with

## handling that. Set this variable to 403 to return HTTPForbidden

auth_ret_code =

Clients must send JSON encoded JSON-RPC requests::

    {

        "id: "<id>",

        "api_key": "<api_key>",

        "method": "<method_name>",

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

    }

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

        --data-binary '{"id":1,"api_key":"xe7cdb2v278e4evbdf5vs04v832v0efvcbcve4a3","method":"pull","args":{"repo":"CPython"}}'

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.

 - *method*, the name of the method to call -- a list of available methods can be found below.

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

.. note::

    api_key can be found or set on the user account page.

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

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,

This allows you to easily use ssh for accessing repositories.

In order to use ssh you need to make sure that your web server and the users'

login accounts have the correct permissions set on the appropriate directories.

.. note:: These permissions are independent of any permissions you

          have set up using the Kallithea web interface.

If your main directory (the same as set in Kallithea settings) is for

example set to ``/srv/repos`` and the repository you are using is

named ``kallithea``, then to clone via ssh you should run::

Using other external tools such as mercurial-server_ or using ssh key-based

authentication is fully supported.

.. note:: In an advanced setup, in order for your ssh access to use

          the same permissions as set up via the Kallithea web

          interface, you can create an authentication hook to connect

          to the Kallithea db and run check functions for permissions

          against that.

Setting up Whoosh full text search

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

Choose *Admin > Authentication*, click the ``kallithea.lib.auth_modules.auth_ldap`` button

and then *Save*, to enable the LDAP plugin and configure its settings.

Here's a typical LDAP setup::

 Connection settings

 Enable LDAP          = checked

 Port                 = 389

 Account              = <account>

 Password             = <password>

 Connection Security  = LDAPS connection

 Certificate Checks   = DEMAND

 Search settings

 Base DN              = CN=users,DC=host,DC=example,DC=org

 LDAP Filter          = (&(objectClass=user)(!(objectClass=computer)))

 LDAP Search Scope    = SUBTREE

 Attribute mappings

   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,

and have that replaced with a URL to the issue. To enable this simply

uncomment the following variables in the ini file::

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

    issue_prefix = #

``issue_pat`` is the regular expression describing which strings in

commit messages will be treated as issue references. A match group in

parentheses should be used to specify the actual issue id.

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

Matched issue references are replaced with the link specified in

``issue_server_link``. ``{id}`` is replaced with the issue ID, and

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

generate a URL in the format:

.. code-block:: html

If needed, more than one pattern can be specified by appending a unique suffix to

the variables. For example::

    issue_pat_wiki = (?:wiki-)(.+)

    issue_prefix_wiki = WIKI-

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

such reference will be transformed into:

.. code-block:: html

Hook management

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

Hooks can be managed in similar way to that used in ``.hgrc`` files.

To manage hooks, choose *Admin > Settings > Hooks*.

The built-in hooks cannot be modified, though they can be enabled or disabled in the *VCS* section.

To add another custom hook simply fill in the first textbox with

``<name>.<hook_type>`` and the second with the hook path. Example hooks

.. code-block:: nginx

    upstream kallithea {

        server 127.0.0.1:5000;

        # add more instances for load balancing

        #server 127.0.0.1:5001;

        #server 127.0.0.1:5002;

    }

    ## gist alias

    server {

       listen          443;

       access_log      /var/log/nginx/gist.access.log;

       error_log       /var/log/nginx/gist.error.log;

       ssl on;

       ssl_certificate     gist.your.kallithea.server.crt;

       ssl_certificate_key gist.your.kallithea.server.key;

       ssl_session_timeout 5m;

       ssl_protocols SSLv3 TLSv1;

       ssl_ciphers DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:EDH-RSA-DES-CBC3-SHA:AES256-SHA:DES-CBC3-SHA:AES128-SHA:RC4-SHA:RC4-MD5;

       ssl_prefer_server_ciphers on;

    }

    server {

       listen          443;

       access_log      /var/log/nginx/kallithea.access.log;

       error_log       /var/log/nginx/kallithea.error.log;

       ssl on;

       ssl_certificate     your.kallithea.server.crt;

       ssl_certificate_key your.kallithea.server.key;

       ssl_session_timeout 5m;

       ssl_protocols SSLv3 TLSv1;

       ssl_ciphers DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:EDH-RSA-DES-CBC3-SHA:AES256-SHA:DES-CBC3-SHA:AES128-SHA:RC4-SHA:RC4-MD5;

       ssl_prefer_server_ciphers on;

    client_body_buffer_size     128k;

    large_client_header_buffers 8 64k;

Apache virtual host reverse proxy example

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

Here is a sample configuration file for Apache using proxy:

.. code-block:: apache

    <VirtualHost *:80>

            <Proxy *>

              # For Apache 2.4 and later:

              Require all granted

              # For Apache 2.2 and earlier, instead use:

              # Order allow,deny

              # Allow from all

            </Proxy>

            #important !

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

Creating a pull request

  You can create a new pull request for the changes of a particular changeset

  (and its ancestors) by selecting it and clicking the ``Open new pull request

  for selected changesets`` button.

Permanent repository URLs

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

Due to the complicated nature of repository grouping, URLs of repositories

can often change. For example, a repository originally accessible from::

would get a new URL after moving it to test_group::

Such moving of a repository to a group can be an issue for build systems and

other scripts where the repository paths are hardcoded. To mitigate this,

Kallithea provides permanent URLs using the repository ID prefixed with an

underscore. In all Kallithea URLs, for example those for the changelog and the

file view, a repository name can be replaced by this ``_ID`` string. Since IDs

are always the same, moving the repository to a different group will not affect

such URLs.

In the example, the repository could also be accessible as::

The ID of a given repository can be shown from the repository ``Summary`` page,

by selecting the ``Show by ID`` button next to ``Clone URL``.

Email notifications

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

With email settings properly configured in the Kallithea

configuration file, Kallithea will send emails on user registration and when

errors occur.

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.

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

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

In general, the Admin settings should be self-explanatory and will not be

described in more detail in this documentation. However, there are a few

features that merit further explanation.

import sys

import argparse

from kallithea.bin.base import json, api_call, RcConf, FORMAT_JSON, FORMAT_PRETTY

def argparser(argv):

    usage = (

      "kallithea-api [-h] [--format=FORMAT] [--apikey=APIKEY] [--apihost=APIHOST] "

      "[--config=CONFIG] [--save-config] "

      "METHOD <key:val> <key2:val> ...\n"

    )

    parser = argparse.ArgumentParser(description='Kallithea API cli',

                                     usage=usage)

    ## config

    group = parser.add_argument_group('config')

    group.add_argument('--apikey', help='api access key')

    group.add_argument('--apihost', help='api host')

    group.add_argument('--config', help='config file')

    group.add_argument('--save-config', action='store_true', help='save the given config into a file')

import stat

import argparse

import fileinput

from kallithea.bin.base import json, api_call, RcConf, FORMAT_JSON, FORMAT_PRETTY

def argparser(argv):

    usage = (

      "kallithea-gist [-h] [--format=FORMAT] [--apikey=APIKEY] [--apihost=APIHOST] "

      "[--config=CONFIG] [--save-config] [GIST OPTIONS] "

      "[filename or stdin use - for terminal stdin ]\n"

    )

    parser = argparse.ArgumentParser(description='Kallithea Gist cli',

                                     usage=usage)

    ## config

    group = parser.add_argument_group('config')

    group.add_argument('--apikey', help='api access key')

    group.add_argument('--apihost', help='api host')

    group.add_argument('--config', help='config file path DEFAULT: ~/.config/kallithea')

    group.add_argument('--save-config', action='store_true',

                       help='save the given config into a file')

[default]

api_user = admin

api_key = XXXXXXXXXXXX

ldap_key = XXXXXXXXX

sync_users = True

#email_to = admin@example.com another_admin@example.com

<%text>## 'From' header for error emails. You can optionally add a name.</%text>

<%text>## Default:</%text>

#error_email_from = pylons@yourapp.com

<%text>## Examples:</%text>

#error_email_from = Kallithea Errors <kallithea-noreply@example.com>

#error_email_from = paste_error@example.com

<%text>## SMTP server settings</%text>

<%text>## Only smtp_server is mandatory. All other settings take the specified default</%text>

<%text>## values.</%text>

#smtp_username =

#smtp_password =

#smtp_port = 25

#smtp_use_tls = false

#smtp_use_ssl = false

<%text>## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).</%text>

<%text>## If empty, use any of the authentication parameters supported by the server.</%text>

#smtp_auth =

[server:main]

%if http_server == 'paste':

<%text>## PASTE ##</%text>

<%text>## RSS feed options</%text>

rss_cut_off_limit = 256000

rss_items_per_page = 10

rss_include_diff = false

<%text>## options for showing and identifying changesets</%text>

show_sha_length = 12

show_revision_number = false

<%text>## gist URL alias, used to create nicer urls for gist. This should be an</%text>

<%text>## url that does rewrites to _admin/gists/<gistid>.</%text>

gist_alias_url =

<%text>## white list of API enabled controllers. This allows to add list of</%text>

<%text>## controllers to which access will be enabled by api_key. eg: to enable</%text>

<%text>## api access to raw_files put `FilesController:raw`, to enable access to patches</%text>

<%text>## add `ChangesetController:changeset_patch`. This list should be "," separated</%text>

<%text>## Syntax is <ControllerClass>:<function>. Check debug logs for generated names</%text>

<%text>## Recommended settings below are commented out:</%text>

api_access_controllers_whitelist =

#    ChangesetController:changeset_patch,

#    ChangesetController:changeset_raw,

#    FilesController:raw,

<%text>## comment out issue_pat, issue_server, issue_prefix to enable</%text>

<%text>## pattern to get the issues from commit messages</%text>

<%text>## default one used here is #<numbers> with a regex passive group for `#`</%text>

<%text>## {id} will be all groups matched from this pattern</%text>

issue_pat = (?:\s*#)(\d+)

<%text>## server url to the issue, each {id} will be replaced with match</%text>

<%text>## fetched from the regex and {repo} is replaced with full repository name</%text>

<%text>## including groups {repo_name} is replaced with just name of repo</%text>

<%text>## prefix to add to link to indicate it's an url</%text>

<%text>## #314 will be replaced by <issue_prefix><id></%text>

issue_prefix = #

<%text>## issue_pat, issue_server_link, issue_prefix can have suffixes to specify</%text>

<%text>## multiple patterns, to other issues server, wiki or others</%text>

<%text>## below an example how to create a wiki pattern</%text>

#issue_pat_wiki = (?:wiki-)(.+)

#issue_prefix_wiki = WIKI-

<%text>## instance-id prefix</%text>

<%text>## a prefix key for this instance used for cache invalidation when running</%text>

<%text>## multiple instances of kallithea, make sure it's globally unique for</%text>

<%text>## all running kallithea instances. Leave empty if you don't use it</%text>

instance_id =

<%text>## alternative return HTTP header for failed authentication. Default HTTP</%text>

<%text>## response is 401 HTTPUnauthorized. Currently Mercurial clients have trouble with</%text>

<%text>## handling that. Set this variable to 403 to return HTTPForbidden</%text>

auth_ret_code =

#email_to = admin@example.com another_admin@example.com

## 'From' header for error emails. You can optionally add a name.

## Default:

#error_email_from = pylons@yourapp.com

## Examples:

#error_email_from = Kallithea Errors <kallithea-noreply@example.com>

#error_email_from = paste_error@example.com

## SMTP server settings

## Only smtp_server is mandatory. All other settings take the specified default

## values.

#smtp_username =

#smtp_password =

#smtp_port = 25

#smtp_use_tls = false

#smtp_use_ssl = false

## SMTP authentication parameters to use (e.g. LOGIN PLAIN CRAM-MD5, etc.).

## If empty, use any of the authentication parameters supported by the server.

#smtp_auth =

[server:main]

## PASTE ##

#use = egg:Paste#http

## RSS feed options

rss_cut_off_limit = 256000

rss_items_per_page = 10

rss_include_diff = false

## options for showing and identifying changesets

show_sha_length = 12

show_revision_number = false

## gist URL alias, used to create nicer urls for gist. This should be an

## url that does rewrites to _admin/gists/<gistid>.

gist_alias_url =

## white list of API enabled controllers. This allows to add list of

## controllers to which access will be enabled by api_key. eg: to enable

## api access to raw_files put `FilesController:raw`, to enable access to patches

## add `ChangesetController:changeset_patch`. This list should be "," separated

## Syntax is <ControllerClass>:<function>. Check debug logs for generated names

## Recommended settings below are commented out:

api_access_controllers_whitelist =

#    ChangesetController:changeset_patch,

#    ChangesetController:changeset_raw,

#    FilesController:raw,

## comment out issue_pat, issue_server, issue_prefix to enable

## pattern to get the issues from commit messages

## default one used here is #<numbers> with a regex passive group for `#`

## {id} will be all groups matched from this pattern

issue_pat = (?:\s*#)(\d+)

## server url to the issue, each {id} will be replaced with match

## fetched from the regex and {repo} is replaced with full repository name

## including groups {repo_name} is replaced with just name of repo

## prefix to add to link to indicate it's an url

## #314 will be replaced by <issue_prefix><id>

issue_prefix = #

## issue_pat, issue_server_link, issue_prefix can have suffixes to specify

## multiple patterns, to other issues server, wiki or others

## below an example how to create a wiki pattern

#issue_pat_wiki = (?:wiki-)(.+)

#issue_prefix_wiki = WIKI-

## instance-id prefix

## a prefix key for this instance used for cache invalidation when running

## multiple instances of kallithea, make sure it's globally unique for

## all running kallithea instances. Leave empty if you don't use it

instance_id =

## alternative return HTTP header for failed authentication. Default HTTP

## response is 401 HTTPUnauthorized. Currently Mercurial clients have trouble with

## handling that. Set this variable to 403 to return HTTPForbidden

auth_ret_code =

class MailResponse(object):

    """

    You are given MailResponse objects from the lamson.view methods, and

    whenever you want to generate an email to send to someone.  It has the

    same basic functionality as MailRequest, but it is designed to be written

    to, rather than read from (although you can do both).

    You can easily set a Body or Html during creation or after by passing it

    as __init__ parameters, or by setting those attributes.

    You can initially set the From, To, and Subject, but they are headers so

    The message is not fully crafted until right when you convert it with

    MailResponse.to_message.  This lets you change it and work with it, then

    send it out when it's ready.

    """

    def __init__(self, To=None, From=None, Subject=None, Body=None, Html=None,

                 separator="; "):

        self.Body = Body

        self.Html = Html

        self.base = MailBase([('To', To), ('From', From), ('Subject', Subject)])

        self.multipart = self.Body and self.Html

        self.attachments = []

]

# Invoke websetup with the current config file

# SetupCommand('setup-app').run([config_file])

environ = {}

#SOME GLOBALS FOR TESTS

TESTS_TMP_PATH = jn('/', 'tmp', 'rc_test_%s' % _RandomNameSequence().next())

TEST_USER_ADMIN_LOGIN = 'test_admin'

TEST_USER_ADMIN_PASS = 'test12'

TEST_USER_REGULAR_LOGIN = 'test_regular'

TEST_USER_REGULAR_PASS = 'test12'

TEST_USER_REGULAR2_LOGIN = 'test_regular2'

TEST_USER_REGULAR2_PASS = 'test12'

HG_REPO = 'vcs_test_hg'

GIT_REPO = 'vcs_test_git'

NEW_HG_REPO = 'vcs_test_hg_new'

NEW_GIT_REPO = 'vcs_test_git_new'

HG_FORK = 'vcs_test_hg_fork'

GIT_FORK = 'vcs_test_git_fork'

## VCS

SCM_TESTS = ['hg', 'git']

            fixture.destroy_repo(repo_name)

    def test_api_get_locks_with_userid(self):

        id_, params = _build_data(self.apikey, 'get_locks',

                                  userid=TEST_USER_REGULAR_LOGIN)

        response = api_call(self, params)

        expected = []

        self._compare_ok(id_, expected, given=response.body)

    def test_api_create_existing_user(self):

        id_, params = _build_data(self.apikey, 'create_user',

                                  username=TEST_USER_ADMIN_LOGIN,

                                  password='trololo')

        response = api_call(self, params)

        expected = "user `%s` already exist" % TEST_USER_ADMIN_LOGIN

        self._compare_error(id_, expected, given=response.body)

    def test_api_create_user_with_existing_email(self):

        id_, params = _build_data(self.apikey, 'create_user',

                                  username=TEST_USER_ADMIN_LOGIN + 'new',

                                  email=TEST_USER_REGULAR_EMAIL,

                                  password='trololo')

        response = api_call(self, params)

        expected = "email `%s` already exist" % TEST_USER_REGULAR_EMAIL

        self._compare_error(id_, expected, given=response.body)

    def test_api_create_user(self):

        username = 'test_new_api_user'

        id_, params = _build_data(self.apikey, 'create_user',

                                  username=username,

                                  email=email,

                                  password='trololo')

        response = api_call(self, params)

        usr = User.get_by_username(username)

        ret = dict(

            msg='created new user `%s`' % username,

            user=jsonify(usr.get_api_data())

        )

        try:

            expected = ret

            self._compare_ok(id_, expected, given=response.body)

        finally:

            fixture.destroy_user(usr.user_id)

    def test_api_create_user_without_password(self):

        username = 'test_new_api_user_passwordless'

        id_, params = _build_data(self.apikey, 'create_user',

                                  username=username,

                                  email=email)

        response = api_call(self, params)

        usr = User.get_by_username(username)

        ret = dict(

            msg='created new user `%s`' % username,

            user=jsonify(usr.get_api_data())

        )

        try:

            expected = ret

            self._compare_ok(id_, expected, given=response.body)

        finally:

            fixture.destroy_user(usr.user_id)

    def test_api_create_user_with_extern_name(self):