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

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

# 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

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

## Email settings                                                             ##

##                                                                            ##

## Refer to the documentation ("Email settings") for more details.            ##

##                                                                            ##

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

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

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

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

## Default:

#app_email_from = Kallithea

## Examples:

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

#app_email_from = kallithea-noreply@example.com

## Subject prefix for application emails.

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

## Default:

#email_prefix =

## Example:

#email_prefix = [Kallithea]

## Recipients for error emails and fallback recipients of application mails.

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

## '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_server = smtp.example.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

## max request before thread respawn

## option to use threads of process

#use_threadpool = true

## WAITRESS ##

use = egg:waitress#main

## number of worker threads

## 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.example.com/{gistid}. Empty means use the internal

## Kallithea url, ie. http[s]://kallithea.example.com/_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://issues.example.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://wiki.example.com/some-id

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

#issue_server_link_wiki = https://wiki.example.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 Mercurial clients have trouble 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

## allows to change the repository location in settings page

allow_repo_location_change = True

## allows to setup custom hooks in settings page

allow_custom_hooks_settings = True

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

###        CELERY CONFIG        ####

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

use_celery = false

broker.host = localhost

broker.vhost = rabbitmqhost

broker.port = 5672

broker.user = rabbitmq

broker.password = qweqwe

celery.imports = kallithea.lib.celerylib.tasks

celery.result.backend = amqp

celery.result.dburi = amqp://

celery.result.serialier = json

#celery.send.task.error.emails = true

#celery.amqp.task.result.expires = 18000

celeryd.concurrency = 2

#celeryd.log.file = celeryd.log

celeryd.log.level = DEBUG

celeryd.max.tasks.per.child = 1

## tasks will never be sent to the queue, but executed locally instead.

celery.always.eager = false

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

###         BEAKER CACHE        ####

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

beaker.cache.data_dir = %(here)s/data/cache/data

beaker.cache.lock_dir = %(here)s/data/cache/lock

beaker.cache.regions = short_term,long_term,sql_cache_short

beaker.cache.short_term.type = memory

beaker.cache.short_term.expire = 60

beaker.cache.short_term.key_length = 256

beaker.cache.long_term.type = memory

beaker.cache.long_term.expire = 36000

beaker.cache.long_term.key_length = 256

beaker.cache.sql_cache_short.type = memory

beaker.cache.sql_cache_short.expire = 10

beaker.cache.sql_cache_short.key_length = 256

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

###       BEAKER SESSION        ####

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

## Name of session cookie. Should be unique for a given host and path, even when running

## on different ports. Otherwise, cookie sessions will be shared and messed up.

beaker.session.key = kallithea

## Sessions should always only be accessible by the browser, not directly by JavaScript.

beaker.session.httponly = true

## Session lifetime. 2592000 seconds is 30 days.

beaker.session.timeout = 2592000

## Server secret used with HMAC to ensure integrity of cookies.

beaker.session.secret = development-not-secret

## Further, encrypt the data with AES.

#beaker.session.encrypt_key = <key_for_encryption>

#beaker.session.validate_key = <validation_key>

## Type of storage used for the session, current types are

## dbm, file, memcached, database, and memory.

## File system storage of session data. (default)

#beaker.session.type = file

## Cookie only, store all session data inside the cookie. Requires secure secrets.

#beaker.session.type = cookie

## Database storage of session data.

#beaker.session.type = ext:database

#beaker.session.sa.url = postgresql://postgres:qwe@localhost/kallithea

#beaker.session.table_name = db_session

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

## ERROR HANDLING SYSTEMS ##

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

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

### [appenlight] ###

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

## AppEnlight is tailored to work with Kallithea, see

## http://appenlight.com for details how to obtain an account

## you must install python package `appenlight_client` to make it work

## appenlight enabled

appenlight = false

appenlight.server_url = https://api.appenlight.com

appenlight.api_key = YOUR_API_KEY

## TWEAK AMOUNT OF INFO SENT HERE

## enables 404 error logging (default False)

appenlight.report_404 = false

## time in seconds after request is considered being slow (default 1)

appenlight.slow_request_time = 1

## record slow requests in application

## (needs to be enabled for slow datastore recording and time tracking)

appenlight.slow_requests = true

## enable hooking to application loggers

#appenlight.logging = true

## minimum log level for log capture

#appenlight.logging.level = WARNING

## send logs only from erroneous/slow requests

## (saves API quota for intensive logging)

appenlight.logging_on_error = false

## list of additonal keywords that should be grabbed from environ object

## can be string with comma separated list of words in lowercase

## (by default client will always send following info:

## 'REMOTE_USER', 'REMOTE_ADDR', 'SERVER_NAME', 'CONTENT_TYPE' + all keys that

## start with HTTP* this list be extended with additional keywords here

appenlight.environ_keys_whitelist =

## list of keywords that should be blanked from request object

## can be string with comma separated list of words in lowercase

## (by default client will always blank keys that contain following words

## 'password', 'passwd', 'pwd', 'auth_tkt', 'secret', 'csrf'

## this list be extended with additional keywords set here

appenlight.request_keys_blacklist =

## list of namespaces that should be ignores when gathering log entries

## can be string with comma separated list of namespaces

## (by default the client ignores own entries: appenlight_client.client)

appenlight.log_namespace_blacklist =

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

### [sentry] ###

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

## sentry is a alternative open source error aggregator

## you must install python packages `sentry` and `raven` to enable

sentry.dsn = YOUR_DNS

sentry.servers =

sentry.name =

sentry.key =

sentry.public_key =

sentry.secret_key =

sentry.project =

sentry.site =

sentry.include_paths =

sentry.exclude_paths =

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

## WARNING: *THE LINE BELOW MUST BE UNCOMMENTED ON A PRODUCTION ENVIRONMENT*  ##

## Debug mode will enable the interactive debugging tool, allowing ANYONE to  ##

## execute malicious code after an exception is raised.                       ##

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

#set debug = false

set debug = true

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

###       LOGVIEW CONFIG       ###

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

logview.sqlalchemy = #faa

logview.pylons.templating = #bfb

logview.pylons.util = #eee

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

### DB CONFIGS - EACH DB WILL HAVE IT'S OWN CONFIG    ###

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

# SQLITE [default]

sqlalchemy.db1.url = sqlite:///%(here)s/kallithea.db?timeout=60

# POSTGRESQL

#sqlalchemy.db1.url = postgresql://user:pass@localhost/kallithea

# MySQL

#sqlalchemy.db1.url = mysql://user:pass@localhost/kallithea

# see sqlalchemy docs for others

sqlalchemy.db1.echo = false

sqlalchemy.db1.pool_recycle = 3600

sqlalchemy.db1.convert_unicode = true

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

### LOGGING CONFIGURATION   ####

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

[loggers]

keys = root, routes, kallithea, sqlalchemy, beaker, templates, whoosh_indexer

[handlers]

keys = console, console_sql

[formatters]

keys = generic, color_formatter, color_formatter_sql

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

## LOGGERS ##

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

[logger_root]

level = NOTSET

handlers = console

[logger_routes]

level = DEBUG

handlers =

qualname = routes.middleware

## "level = DEBUG" logs the route matched and routing variables.

propagate = 1

[logger_beaker]

level = DEBUG

handlers =

qualname = beaker.container

propagate = 1

[logger_templates]

level = INFO

handlers =

qualname = pylons.templating

propagate = 1

[logger_kallithea]

level = DEBUG

handlers =

qualname = kallithea

propagate = 1

[logger_sqlalchemy]

level = INFO

handlers = console_sql

qualname = sqlalchemy.engine

propagate = 0

[logger_whoosh_indexer]

level = DEBUG

handlers =

qualname = whoosh_indexer

propagate = 1

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

## HANDLERS ##

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

[handler_console]

class = StreamHandler

args = (sys.stderr,)

#level = INFO

#formatter = generic

level = DEBUG

formatter = color_formatter

[handler_console_sql]

class = StreamHandler

args = (sys.stderr,)

#level = WARN

#formatter = generic

level = DEBUG

formatter = color_formatter_sql

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

## FORMATTERS ##

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

[formatter_generic]

format = %(asctime)s.%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s

datefmt = %Y-%m-%d %H:%M:%S

[formatter_color_formatter]

class = kallithea.lib.colored_formatter.ColorFormatter

format = %(asctime)s.%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s

datefmt = %Y-%m-%d %H:%M:%S

[formatter_color_formatter_sql]

class = kallithea.lib.colored_formatter.ColorFormatterSql

format = %(asctime)s.%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s

datefmt = %Y-%m-%d %H:%M:%S

.. _setup:

=====

Setup

=====

Setting up Kallithea

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

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

          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. The IP address and port is configurable via the

  configuration file created in the previous step.

- Log in to Kallithea using the admin account created when running ``setup-db``.

- 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 one can create an ``rcextensions`` package that extends Kallithea

functionality.

To generate a skeleton extensions package, run::

    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@kallithea.example.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

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

Kallithea provides full text search of repositories using `Whoosh`__.

.. __: https://pythonhosted.org/Whoosh/

For an incremental index build, run::

    paster make-index my.ini

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.

.. _ldap-setup:

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.

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

 Host                 = host.example.com

 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

 Email Attribute      = mail

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.