################################################################################

################################################################################

# Kallithea - Development config:                                              #

# listening on *:5000                                                          #

# sqlite and kallithea.db                                                      #

# initial_repo_scan = true                                                     #

# set debug = true                                                             #

# verbose and colorful logging                                                 #

#                                                                              #

# The %(here)s variable will be replaced with the parent directory of this file#

################################################################################

################################################################################

[DEFAULT]

debug = true

pdebug = false

################################################################################

##                                                                            ##

##                                                                            ##

## It is recommended to use a valid sender address that passes access         ##

## validation and spam filtering in mail servers.                             ##

################################################################################

## Default:

#app_email_from = Kallithea

## Examples:

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

#app_email_from = kallithea-noreply@example.com

## A space between this prefix and the real subject is automatically added.

## Default:

#email_prefix =

## Example:

#email_prefix = [Kallithea]

## Multiple addresses can be specified, space-separated.

## Only addresses are allowed, do not add any name part.

## Default:

#email_to =

## Examples:

#email_to = admin@example.com

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

## 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_server = mail.server.com

#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

## nr of worker threads to spawn

#threadpool_workers = 5

## max request before thread respawn

#threadpool_max_requests = 10

## option to use threads of process

#use_threadpool = true

## WAITRESS ##

use = egg:waitress#main

## number of worker threads

threads = 5

## MAX BODY SIZE 100GB

max_request_body_size = 107374182400

## use poll instead of select, fixes fd limits, may not work on old

## windows systems.

#asyncore_use_poll = True

## GUNICORN ##

#use = egg:gunicorn#main

## number of process workers. You must set `instance_id = *` when this option

## is set to more than one worker

#workers = 1

## process name

#proc_name = kallithea

## type of worker class, one of sync, eventlet, gevent, tornado

## recommended for bigger setup is using of of other than sync one

#worker_class = sync

#max_requests = 1000

## ammount of time a worker can handle request before it gets killed and

## restarted

#timeout = 3600

## UWSGI ##

## run with uwsgi --ini-paste-logged <inifile.ini>

#[uwsgi]

#socket = /tmp/uwsgi.sock

#master = true

#http = 127.0.0.1:5000

## set as deamon and redirect all output to file

#daemonize = ./uwsgi_kallithea.log

## master process PID

#pidfile = ./uwsgi_kallithea.pid

## stats server with workers statistics, use uwsgitop

## for monitoring, `uwsgitop 127.0.0.1:1717`

#stats = 127.0.0.1:1717

#memory-report = true

## log 5XX errors

#log-5xx = true

## Set the socket listen queue size.

#listen = 256

## Gracefully Reload workers after the specified amount of managed requests

## (avoid memory leaks).

#max-requests = 1000

## enable large buffers

#buffer-size = 65535

## socket and http timeouts ##

#http-timeout = 3600

#socket-timeout = 3600

## Log requests slower than the specified number of milliseconds.

#log-slow = 10

## Exit if no app can be loaded.

#need-app = true

## Set lazy mode (load apps in workers instead of master).

#lazy = true

## scaling ##

## set cheaper algorithm to use, if not set default will be used

#cheaper-algo = spare

## minimum number of workers to keep at all times

#cheaper = 1

## number of workers to spawn at startup

#cheaper-initial = 1

## maximum number of workers that can be spawned

#workers = 4

## how many workers should be spawned at a time

#cheaper-step = 1

## COMMON ##

host = 0.0.0.0

port = 5000

## middleware for hosting the WSGI application under a URL prefix

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

## cs de fr hu ja nl_BE pl pt_BR ru sk zh_CN zh_TW

lang =

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 = false

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

.. _contributing:

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

Contributing to Kallithea

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

Kallithea is developed and maintained by its users. Please join us and scratch

your own itch.

Infrastructure

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

The main repository is hosted at Our Own Kallithea (aka OOK) on

https://kallithea-scm.org/repos/kallithea/ (which is our self-hosted instance

of Kallithea).

For now, we use Bitbucket_ for `Pull Requests`_ and `Issue Tracker`_ services. The

issue tracker is for tracking bugs, not for support, discussion, or ideas -

please use the `mailing list`_ to reach the community.

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.

Getting started

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

To get started with development::

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

        cd kallithea

        virtualenv ../kallithea-venv

        source ../kallithea-venv/bin/activate

        python setup.py develop

        paster make-config Kallithea my.ini

        paster setup-db my.ini --user=user --email=user@example.com --password=password --repos=/tmp

        paster serve my.ini --reload &

        firefox http://127.0.0.1:5000/

You can also start out by forking https://bitbucket.org/conservancy/kallithea

on Bitbucket_ and create a local clone of your own fork.

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

run ``tox`` for python2.6-2.7 with multiple database test.

When using `nosetests`, the `test.ini` file is used with an SQLite database. Edit

this file to change your testing enviroment.

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

    paster serve test.ini --pid-file=test.pid --daemon

    KALLITHEA_WHOOSH_TEST_DISABLE=1 KALLITHEA_NO_TMP_PATH=1 nosetests

    kill -9 $(cat test.pid)

You can run individual tests by specifying their path as argument to nosetests.

nosetests also has many more options, see `nosetests -h`. Some useful options

are::

    -x, --stop            Stop running tests after the first error or failure

    -s, --nocapture       Don't capture stdout (any stdout output will be

                          printed immediately) [NOSE_NOCAPTURE]

    --failed              Run the tests that failed in the last test run.

Coding/contribution guidelines

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

Kallithea is GPLv3 and we assume all contributions are made by the

committer/contributor and under GPLv3 unless explicitly stated. We do care a

lot about preservation of copyright and license information for existing code

that is brought into the project.

We don't have a formal coding/formatting standard. We are currently using a mix

of Mercurial (http://mercurial.selenic.com/wiki/CodingStyle), pep8, and

consistency with existing code. Run whitespacecleanup.sh to avoid stupid

whitespace noise in your patches.

We support both Python 2.6.x and 2.7.x and nothing else. For now we don't care

about Python 3 compatibility.

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.

Html templates should use 2 spaces for indentation ... but be pragmatic. We

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

semantic markup with classes and ids that can be used for styling and testing.

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

display:none).

JavaScript must use ';' between/after statements. Indentation 4 spaces. Inline

multiline functions should be indented two levels - one for the () and one for

{}. jQuery value arrays should have a leading $.

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

bug fixes, put "(Issue #123)" at the end of this line.

Contributions will be accepted in most formats - such as pull requests on

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.

Everything non-sensitive should be discussed in public - preferably on the

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

elsewhere (for example in a pull request) until they are ready.

.. _translations:

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

"Roadmap"

---------

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

wiki_ for some ideas of places we might want to go - contributions in these

areas are very welcome.

Thank you for your contribution!

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

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

.. _Issue Tracker: https://bitbucket.org/conservancy/kallithea/issues?status=new&status=open

.. _Pull Requests: https://bitbucket.org/conservancy/kallithea/pull-requests

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

.. _index:

Kallithea Documentation

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

**Readme**

.. toctree::

   :maxdepth: 1

   readme

**Installation**

.. toctree::

   :maxdepth: 1

   overview

   installation

   installation_win

   installation_win_old

   installation_iis

   setup

**Usage**

.. toctree::

   :maxdepth: 1

   usage/general

   usage/vcs_support

   usage/locking

   usage/statistics

**Administrators Guide**

.. toctree::

   :maxdepth: 1

   usage/performance

   usage/backup

   usage/debugging

   usage/troubleshooting

**Develop**

.. toctree::

   :maxdepth: 1

   contributing

   changelog

**API**

.. toctree::

   :maxdepth: 1

   api/api

   api/models

Other topics

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

* :ref:`genindex`

* :ref:`search`

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

.. _python: http://www.python.org/

.. _django: http://www.djangoproject.com/

.. _mercurial: http://mercurial.selenic.com/

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

.. _subversion: http://subversion.tigris.org/

.. _git: http://git-scm.com/

.. _celery: http://celeryproject.org/

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

.. _vcs: http://pypi.python.org/pypi/vcs

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 process can be fully automated, example for lazy::

    paster setup-db my.ini --user=nn --password=secret --email=nn@your.kallithea.server --repos=/srv/repos

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

          denied errors unless it has write access.

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

  http://127.0.0.1:5000. This ip and port is configurable via the my.ini

  file created in previous step

- Use the admin account you created above when running ``setup-db``

  to login to the web app.

- 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

  repositories

Extensions

----------

Optionally users can create an ``rcextensions`` package that extends Kallithea

functionality. To do this simply execute::

    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,

for example for sending signals to build-bots such as Jenkins.

See the ``__init__.py`` file inside the generated ``rcextensions`` package

for more details.

Using Kallithea with SSH

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

Kallithea currently only hosts repositories using http and https. (The addition

of ssh hosting is a planned future feature.) However you can easily use ssh in

parallel with Kallithea. (Repository access via ssh is a standard "out of

the box" feature of Mercurial_ and you can use this to access any of the

repositories that Kallithea is hosting. See PublishingRepositories_)

Kallithea repository structures are kept in directories with the same name

as the project. When using repository groups, each group is a subdirectory.

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

    hg clone ssh://user@server.com//srv/repos/kallithea

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

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

The whoosh index can be built by using the paster

command ``make-index``. To use ``make-index`` you must specify the configuration

file that stores the location of the index. You may specify the location of the

repositories (``--repo-location``).  If not specified, this value is retrieved

from the Kallithea database.

It is also possible to specify a comma separated list of

repositories (``--index-only``) to build index only on chooses repositories

skipping any other found in repos location

You may optionally pass the option ``-f`` to enable a full index rebuild. Without

the ``-f`` option, indexing will run always in "incremental" mode.

For an incremental index build use::

    paster make-index my.ini

For a full index rebuild use::

    paster make-index my.ini -f

Building an index for just selected repositories is possible with such command::

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

In order to do periodic index builds and keep your index always up to

date, it is recommended to use a crontab entry.  An example entry

might look like this::

    /path/to/python/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" flag.

Setting up LDAP support

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

Kallithea supports LDAP authentication. In order

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

available via pypi, so you can install it by running::

    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.

LDAP settings are located in the Admin->LDAP section.

Here's a typical LDAP setup::

 Connection settings

 Enable LDAP          = checked

 Host                 = host.example.org

 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

 Login Attribute      = uid

 First Name Attribute = firstName

 Last Name Attribute  = lastName

If your user groups are placed in an Organisation Unit (OU) structure, the Search Settings configuration differs::

 Search settings

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

 LDAP Filter          = (&(memberOf=CN=your user group,OU=subunit,OU=unit,DC=host,DC=example,DC=org)(objectClass=user))

 LDAP Search Scope    = SUBTREE

.. _enable_ldap:

Enable LDAP : required

    Whether to use LDAP for authenticating users.

.. _ldap_host:

Host : required

    LDAP server hostname or IP address. Can be also a comma separated

    list of servers to support LDAP fail-over.

.. _Port:

Port : required

    389 for un-encrypted LDAP, 636 for SSL-encrypted LDAP.

.. _ldap_account:

Account : optional

    Only required if the LDAP server does not allow anonymous browsing of

    records.  This should be a special account for record browsing.  This

    will require `LDAP Password`_ below.

.. _LDAP Password:

Password : optional

    Only required if the LDAP server does not allow anonymous browsing of

    records.

.. _Enable LDAPS:

Connection Security : required

    Defines the connection to LDAP server

    No encryption

        Plain non encrypted connection

    LDAPS connection

        Enable LDAPS connections. It will likely require `Port`_ to be set to

        a different value (standard LDAPS port is 636). When LDAPS is enabled

        then `Certificate Checks`_ is required.

    START_TLS on LDAP connection

        START TLS connection

.. _Certificate Checks:

Certificate Checks : optional

    How SSL certificates verification is handled - this is only useful when

    `Enable LDAPS`_ is enabled.  Only DEMAND or HARD offer full SSL security

    while the other options are susceptible to man-in-the-middle attacks.  SSL

    certificates can be installed to /etc/openldap/cacerts so that the

    DEMAND or HARD options can be used with self-signed certificates or

    certificates that do not have traceable certificates of authority.

    NEVER

        A serve certificate will never be requested or checked.

    ALLOW

        A server certificate is requested.  Failure to provide a

        certificate or providing a bad certificate will not terminate the

        session.

    TRY

        A server certificate is requested.  Failure to provide a

        certificate does not halt the session; providing a bad certificate

        halts the session.

    DEMAND

        A server certificate is requested and must be provided and

        authenticated for the session to proceed.

    HARD

        The same as DEMAND.

.. _Base DN:

Base DN : required

    The Distinguished Name (DN) where searches for users will be performed.

    Searches can be controlled by `LDAP Filter`_ and `LDAP Search Scope`_.

.. _LDAP Filter:

LDAP Filter : optional

    A LDAP filter defined by RFC 2254.  This is more useful when `LDAP

    Search Scope`_ is set to SUBTREE.  The filter is useful for limiting

    which LDAP objects are identified as representing Users for

    authentication.  The filter is augmented by `Login Attribute`_ below.

    This can commonly be left blank.

.. _LDAP Search Scope:

LDAP Search Scope : required

    This limits how far LDAP will search for a matching object.

    BASE

        Only allows searching of `Base DN`_ and is usually not what you

        want.

    ONELEVEL

        Searches all entries under `Base DN`_, but not Base DN itself.

    SUBTREE

        Searches all entries below `Base DN`_, but not Base DN itself.

        When using SUBTREE `LDAP Filter`_ is useful to limit object

        location.

.. _Login Attribute:

Login Attribute : required

    The LDAP record attribute that will be matched as the USERNAME or

    ACCOUNT used to connect to Kallithea.  This will be added to `LDAP

    Filter`_ for locating the User object.  If `LDAP Filter`_ is specified as

    "LDAPFILTER", `Login Attribute`_ is specified as "uid" and the user has

    connected as "jsmith" then the `LDAP Filter`_ will be augmented as below

    ::

        (&(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

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

appropriately configured.

Authentication by container or reverse-proxy

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

Kallithea supports delegating the authentication

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