## COMMON ##

host = 0.0.0.0

port = 5000

## prefix middleware for rc

#[filter:proxy-prefix]

#use = egg:PasteDeploy#prefix

#prefix = /<your-prefix>

[app:main]

use = egg:kallithea

## enable proxy prefix middleware

#filter-with = proxy-prefix

full_stack = true

static_files = true

## Available Languages:

## de en fr ja pl pt_BR ru zh_CN zh_TW

lang = en

cache_dir = %(here)s/data

index_dir = %(here)s/data/index

## perform a full repository scan on each server start, this should be

## set to false after first startup, to allow faster server restarts.

#initial_repo_scan = false

initial_repo_scan = true

## uncomment and set this path to use archive download cache

archive_cache_dir = %(here)s/tarballcache

## change this to unique ID for security

app_instance_uuid = development-not-secret

## cut off limit for large diffs (size in bytes)

cut_off_limit = 256000

## use cache version of scm repo everywhere

vcs_full_cache = true

## force https in Kallithea, fixes https redirects, assumes it's always https

force_https = false

## use Strict-Transport-Security headers

use_htsts = false

## number of commits stats will parse on each iteration

commit_parse_limit = 25

## path to git executable

git_path = git

## git rev filter option, --all is the default filter, if you need to

## hide all refs in changelog switch this to --branches --tags

#git_rev_filter = --branches --tags

## 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 = true

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

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

## example: http://gist.kallithea.server/{gistid}. Empty means use the internal

## Kallithea url, ie. http[s]://your.kallithea.server/_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,

#    FilesController:archivefile

## default encoding used to convert from and to unicode

## can be also a comma seperated list of encoding in case of mixed encodings

default_encoding = utf8

## issue tracker for Kallithea (leave blank to disable, absent for default)

#bugtracker = https://bitbucket.org/conservancy/kallithea/issues

## issue tracking mapping for commits messages

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

issue_server_link = https://myissueserver.com/{repo}/issue/{id}

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

# wiki-some-id -> https://mywiki.com/some-id

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

#issue_server_link_wiki = https://mywiki.com/{id}

#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 HG clients have troubles with

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

auth_ret_code =

## locking return code. When repository is locked return this HTTP code. 2XX

## codes don't break the transactions while 4XX codes do

lock_ret_code = 423

        (&(LDAPFILTER)(uid=jsmith))

.. _ldap_attr_firstname:

First Name Attribute : required

    The LDAP record attribute which represents the user's first name.

.. _ldap_attr_lastname:

Last Name Attribute : required

    The LDAP record attribute which represents the user's last name.

.. _ldap_attr_email:

Email Attribute : required

    The LDAP record attribute which represents the user's email address.

If all data are entered correctly, and python-ldap_ is properly installed

users should be granted access to Kallithea with ldap accounts.  At this

time user information is copied from LDAP into the Kallithea user database.

This means that updates of an LDAP user object may not be reflected as a

user update in Kallithea.

If You have problems with LDAP access and believe You entered correct

information check out the Kallithea logs, any error messages sent from LDAP

will be saved there.

Active Directory

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

Kallithea can use Microsoft Active Directory for user authentication.  This

is done through an LDAP or LDAPS connection to Active Directory.  The

following LDAP configuration settings are typical for using Active

Directory ::

 Base DN              = OU=SBSUsers,OU=Users,OU=MyBusiness,DC=v3sys,DC=local

 Login Attribute      = sAMAccountName

 First Name Attribute = givenName

 Last Name Attribute  = sn

 E-mail Attribute     = mail

All other LDAP settings will likely be site-specific and should be

appropriately configured.

Authentication by container or reverse-proxy

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

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

username that the container/proxy (Apache/Nginx/etc) authenticated and doesn't

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

permissions before the user logs in for the first time.

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.

After setting up your container (see `Apache's WSGI config`_), you'd need

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`_,

`Apache as subdirectory`_ or `Nginx virtual host example`_), you'd need to

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

reverse-proxy setup with basic auth::

    <Location /<someprefix> >

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

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

      SetEnvIf X-Url-Scheme https HTTPS=1

      AuthType Basic

      AuthName "Kallithea authentication"

      AuthUserFile /home/web/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 fetch issue id stored in commit

messages and replace that with an url to this issue. To enable this simply

uncomment following variables in the ini file::

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

    issue_server_link = https://myissueserver.com/{repo}/issue/{id}

    issue_prefix = #

`issue_pat` is the regular expression that will fetch issues from commit messages.

Default regex will match issues in format of #<number> eg. #300.

Matched issues will be replace with the link specified as `issue_server_link`

{id} will be replaced with issue id, and {repo} with repository name.

Since the # is striped `issue_prefix` is added as a prefix to url.

`issue_prefix` can be something different than # if you pass

ISSUE- as issue prefix this will generate an url in format::

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

Hook management

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

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

To access hooks setting click `advanced setup` on Hooks section of Mercurial

Settings in Admin.

There are 4 built in hooks that cannot be changed (only enable/disable by

checkboxes on previos section).

To add another custom hook simply fill in first section with

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

can be found at *kallithea.lib.hooks*.

Changing default encoding

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

By default Kallithea uses utf8 encoding, starting from 1.3 series this

%endif

<%text>## COMMON ##</%text>

host = ${host}

port = ${port}

<%text>## prefix middleware for rc</%text>

#[filter:proxy-prefix]

#use = egg:PasteDeploy#prefix

#prefix = /<your-prefix>

[app:main]

use = egg:kallithea

<%text>## enable proxy prefix middleware</%text>

#filter-with = proxy-prefix

full_stack = true

static_files = true

<%text>## Available Languages:</%text>

<%text>## de en fr ja pl pt_BR ru zh_CN zh_TW</%text>

lang = ${lang}

cache_dir = ${here}/data

index_dir = ${here}/data/index

<%text>## perform a full repository scan on each server start, this should be</%text>

<%text>## set to false after first startup, to allow faster server restarts.</%text>

initial_repo_scan = false

<%text>## uncomment and set this path to use archive download cache</%text>

archive_cache_dir = ${here}/tarballcache

<%text>## change this to unique ID for security</%text>

app_instance_uuid = ${uuid()}

<%text>## cut off limit for large diffs (size in bytes)</%text>

cut_off_limit = 256000

<%text>## use cache version of scm repo everywhere</%text>

vcs_full_cache = true

<%text>## force https in Kallithea, fixes https redirects, assumes it's always https</%text>

force_https = false

<%text>## use Strict-Transport-Security headers</%text>

use_htsts = false

<%text>## number of commits stats will parse on each iteration</%text>

commit_parse_limit = 25

<%text>## path to git executable</%text>

git_path = git

<%text>## git rev filter option, --all is the default filter, if you need to</%text>

<%text>## hide all refs in changelog switch this to --branches --tags</%text>

#git_rev_filter = --branches --tags

<%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 = true

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

<%text>## example: http://gist.kallithea.server/{gistid}. Empty means use the internal</%text>

<%text>## Kallithea url, ie. http[s]://your.kallithea.server/_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,

#    FilesController:archivefile

<%text>## default encoding used to convert from and to unicode</%text>

<%text>## can be also a comma seperated list of encoding in case of mixed encodings</%text>

default_encoding = utf8

<%text>## issue tracker for Kallithea (leave blank to disable, absent for default)</%text>

#bugtracker = https://bitbucket.org/conservancy/kallithea/issues

<%text>## issue tracking mapping for commits messages</%text>

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

issue_server_link = https://myissueserver.com/{repo}/issue/{id}

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

# wiki-some-id -> https://mywiki.com/some-id

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

#issue_server_link_wiki = https://mywiki.com/{id}

#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 HG clients have troubles with</%text>

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

auth_ret_code =

<%text>## locking return code. When repository is locked return this HTTP code. 2XX</%text>

<%text>## codes don't break the transactions while 4XX codes do</%text>

lock_ret_code = 423

## COMMON ##

host = 127.0.0.1

port = 5000

## prefix middleware for rc

#[filter:proxy-prefix]

#use = egg:PasteDeploy#prefix

#prefix = /<your-prefix>

[app:main]

use = egg:kallithea

## enable proxy prefix middleware

#filter-with = proxy-prefix

full_stack = true

static_files = true

## Available Languages:

## de en fr ja pl pt_BR ru zh_CN zh_TW

lang = en

cache_dir = %(here)s/data

index_dir = %(here)s/data/index

## perform a full repository scan on each server start, this should be

## set to false after first startup, to allow faster server restarts.

initial_repo_scan = false

## uncomment and set this path to use archive download cache

archive_cache_dir = %(here)s/tarballcache

## change this to unique ID for security

app_instance_uuid = ${app_instance_uuid}

## cut off limit for large diffs (size in bytes)

cut_off_limit = 256000

## use cache version of scm repo everywhere

vcs_full_cache = true

## force https in Kallithea, fixes https redirects, assumes it's always https

force_https = false

## use Strict-Transport-Security headers

use_htsts = false

## number of commits stats will parse on each iteration

commit_parse_limit = 25

## path to git executable

git_path = git

## git rev filter option, --all is the default filter, if you need to

## hide all refs in changelog switch this to --branches --tags

#git_rev_filter = --branches --tags

## 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 = true

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

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

## example: http://gist.kallithea.server/{gistid}. Empty means use the internal

## Kallithea url, ie. http[s]://your.kallithea.server/_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,

#    FilesController:archivefile

## default encoding used to convert from and to unicode

## can be also a comma seperated list of encoding in case of mixed encodings

default_encoding = utf8

## issue tracker for Kallithea (leave blank to disable, absent for default)

#bugtracker = https://bitbucket.org/conservancy/kallithea/issues

## issue tracking mapping for commits messages

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

issue_server_link = https://myissueserver.com/{repo}/issue/{id}

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

# wiki-some-id -> https://mywiki.com/some-id

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

#issue_server_link_wiki = https://mywiki.com/{id}

#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 HG clients have troubles with

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

auth_ret_code =

## locking return code. When repository is locked return this HTTP code. 2XX

## codes don't break the transactions while 4XX codes do

lock_ret_code = 423

## COMMON ##

host = 127.0.0.1

port = 5000

## prefix middleware for rc

#[filter:proxy-prefix]

#use = egg:PasteDeploy#prefix

#prefix = /<your-prefix>

[app:main]

use = egg:kallithea

## enable proxy prefix middleware

#filter-with = proxy-prefix

full_stack = true

static_files = true

## Available Languages:

## de en fr ja pl pt_BR ru zh_CN zh_TW

lang = en

cache_dir = %(here)s/data

index_dir = %(here)s/data/index

## perform a full repository scan on each server start, this should be

## set to false after first startup, to allow faster server restarts.

initial_repo_scan = false

## uncomment and set this path to use archive download cache

archive_cache_dir = %(here)s/tarballcache

## change this to unique ID for security

app_instance_uuid = change-me

## cut off limit for large diffs (size in bytes)

cut_off_limit = 256000

## use cache version of scm repo everywhere

vcs_full_cache = true

## force https in Kallithea, fixes https redirects, assumes it's always https

force_https = false

## use Strict-Transport-Security headers

use_htsts = false

## number of commits stats will parse on each iteration

commit_parse_limit = 25

## path to git executable

git_path = git

## git rev filter option, --all is the default filter, if you need to

## hide all refs in changelog switch this to --branches --tags

#git_rev_filter = --branches --tags

## 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 = true

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

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

## example: http://gist.kallithea.server/{gistid}. Empty means use the internal

## Kallithea url, ie. http[s]://your.kallithea.server/_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,

#    FilesController:archivefile

## default encoding used to convert from and to unicode

## can be also a comma seperated list of encoding in case of mixed encodings

default_encoding = utf8

## issue tracker for Kallithea (leave blank to disable, absent for default)

#bugtracker = https://bitbucket.org/conservancy/kallithea/issues

## issue tracking mapping for commits messages

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

issue_server_link = https://myissueserver.com/{repo}/issue/{id}

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

# wiki-some-id -> https://mywiki.com/some-id

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

#issue_server_link_wiki = https://mywiki.com/{id}

#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 HG clients have troubles with

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

auth_ret_code =

## locking return code. When repository is locked return this HTTP code. 2XX

## codes don't break the transactions while 4XX codes do

lock_ret_code = 423

host = 127.0.0.1

port = 5000

## prefix middleware for rc

#[filter:proxy-prefix]

#use = egg:PasteDeploy#prefix

#prefix = /<your-prefix>

[app:main]

use = egg:kallithea

## enable proxy prefix middleware

#filter-with = proxy-prefix

full_stack = true

static_files = true

## Available Languages:

## de en fr ja pl pt_BR ru zh_CN zh_TW

lang = en

cache_dir = %(here)s/data

index_dir = %(here)s/data/index

## perform a full repository scan on each server start, this should be

## set to false after first startup, to allow faster server restarts.

#initial_repo_scan = false

initial_repo_scan = true

## uncomment and set this path to use archive download cache

archive_cache_dir = %(here)s/tarballcache

## change this to unique ID for security

app_instance_uuid = test

## cut off limit for large diffs (size in bytes)

cut_off_limit = 256000

## use cache version of scm repo everywhere

#vcs_full_cache = true

vcs_full_cache = false

## force https in Kallithea, fixes https redirects, assumes it's always https