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

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

# 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

Apache virtual host reverse proxy example

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

Here is a sample configuration file for Apache using proxy:

.. code-block:: apache

    <VirtualHost *:80>

            ServerName kallithea.example.com

            <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

            ProxyPreserveHost On

            #kallithea instance

            ProxyPass / http://127.0.0.1:5000/

            ProxyPassReverse / http://127.0.0.1:5000/

            #to enable https use line below

            #SetEnvIf X-Url-Scheme https HTTPS=1

    </VirtualHost>

Additional tutorial

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

Apache as subdirectory

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

Apache subdirectory part:

.. code-block:: apache

    <Location /<someprefix> >

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

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

      SetEnvIf X-Url-Scheme https HTTPS=1

    </Location>

Besides the regular apache setup you will need to add the following line

into ``[app:main]`` section of your .ini file::

    filter-with = proxy-prefix

Add the following at the end of the .ini file::

    [filter:proxy-prefix]

    use = egg:PasteDeploy#prefix

    prefix = /<someprefix>

then change ``<someprefix>`` into your chosen prefix

Apache with mod_wsgi

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

Alternatively, Kallithea can be set up with Apache under mod_wsgi. For

that, you'll need to:

- Install mod_wsgi. If using a Debian-based distro, you can install

  the package libapache2-mod-wsgi::

    aptitude install libapache2-mod-wsgi

- Enable mod_wsgi::

    a2enmod wsgi

- Add global Apache configuration to tell mod_wsgi that Python only will be

  used in the WSGI processes and shouldn't be initialized in the Apache

  processes::

    WSGIRestrictEmbedded On

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

  check that the paths correctly point to where you installed Kallithea

  and its Python Virtual Environment.

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

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

  correctly specified.

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

.. code-block:: apache

        python-home=/srv/kallithea/venv

    WSGIProcessGroup kallithea

    WSGIScriptAlias / /srv/kallithea/dispatch.wsgi

    WSGIPassAuthorization On

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

.. code-block:: apache

    WSGIProcessGroup kallithea

    WSGIScriptAlias / /srv/kallithea/dispatch.wsgi

    WSGIPassAuthorization On

Apache will by default run as a special Apache user, on Linux systems

usually ``www-data`` or ``apache``. If you need to have the repositories

directory owned by a different user, use the user and group options to

WSGIDaemonProcess to set the name of the user and group.

.. note::

   If running Kallithea in multiprocess mode,

   make sure you set ``instance_id = *`` in the configuration so each process

   gets it's own cache invalidation key.

Example WSGI dispatch script:

.. code-block:: python

    import os

    os.environ["HGENCODING"] = "UTF-8"

    os.environ['PYTHON_EGG_CACHE'] = '/srv/kallithea/.egg-cache'

    # sometimes it's needed to set the curent dir

    os.chdir('/srv/kallithea/')

    import site

    site.addsitedir("/srv/kallithea/venv/lib/python2.7/site-packages")

    ini = '/srv/kallithea/my.ini'

    from paste.script.util.logging_config import fileConfig

    fileConfig(ini)

    from paste.deploy import loadapp

    application = loadapp('config:' + ini)

Or using proper virtualenv activation:

.. code-block:: python

    activate_this = '/srv/kallithea/venv/bin/activate_this.py'

    execfile(activate_this, dict(__file__=activate_this))

    import os

    os.environ['HOME'] = '/srv/kallithea'

    ini = '/srv/kallithea/kallithea.ini'

    from paste.script.util.logging_config import fileConfig

    fileConfig(ini)

    from paste.deploy import loadapp

    application = loadapp('config:' + ini)

Other configuration files

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

A number of `example init.d scripts`__ can be found in

the ``init.d`` directory of the Kallithea source.

.. __: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/ .

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

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

.. _Mercurial: https://www.mercurial-scm.org/

.. _Celery: http://celeryproject.org/

.. _Celery documentation: http://docs.celeryproject.org/en/latest/getting-started/index.html

.. _RabbitMQ: http://www.rabbitmq.com/

.. _Redis: http://redis.io/

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

.. _mercurial-server: http://www.lshift.net/mercurial-server.html

.. _PublishingRepositories: https://www.mercurial-scm.org/wiki/PublishingRepositories

.. _performance:

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

Optimizing Kallithea performance

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

When serving a large amount of big repositories, Kallithea can start

performing slower than expected. Because of the demanding nature of handling large

amounts of data from version control systems, here are some tips on how to get

the best performance.

* Kallithea is often I/O bound, and hence a fast disk (SSD/SAN) is

  usually more important than a fast CPU.

* Sluggish loading of the front page can easily be fixed by grouping repositories or by

  increasing cache size (see below). This includes using the lightweight dashboard

  option and ``vcs_full_cache`` setting in .ini file.

Follow these few steps to improve performance of Kallithea system.

1. Increase cache

    Tweak beaker cache settings in the ini file. The actual effect of that

    is questionable.

2. Switch from SQLite to PostgreSQL or MySQL

    SQLite is a good option when having a small load on the system. But due to

    locking issues with SQLite, it is not recommended to use it for larger

    deployments. Switching to MySQL or PostgreSQL will result in an immediate

    performance increase. A tool like SQLAlchemyGrate_ can be used for

    migrating to another database platform.

3. Scale Kallithea horizontally

    Scaling horizontally can give huge performance benefits when dealing with

    large amounts of traffic (many users, CI servers, etc.). Kallithea can be

    - Each instance needs its own .ini file and unique ``instance_id`` set.

    - Each instance's ``data`` storage needs to be configured to be stored on a

      shared disk storage, preferably together with repositories. This ``data``

      dir contains template caches, sessions, whoosh index and is used for

      task locking (so it is safe across multiple instances). Set the

      ``cache_dir``, ``index_dir``, ``beaker.cache.data_dir``, ``beaker.cache.lock_dir``

      variables in each .ini file to a shared location across Kallithea instances

      the message broker should be common to all of them (e.g.,  one

      shared RabbitMQ server)

    - Load balance using round robin or IP hash, recommended is writing LB rules

      that will separate regular user traffic from automated processes like CI

      servers or build bots.

.. _SQLAlchemyGrate: https://github.com/shazow/sqlalchemygrate

## -*- coding: utf-8 -*-

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

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

# Kallithea - config file generated with kallithea-config                      #

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

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

[DEFAULT]

debug = true

pdebug = false

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

<%text>## Email settings                                                             ##</%text>

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

<%text>## Refer to the documentation ("Email settings") for more details.            ##</%text>

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

<%text>## It is recommended to use a valid sender address that passes access         ##</%text>

<%text>## validation and spam filtering in mail servers.                             ##</%text>

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

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

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

#app_email_from = Kallithea

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

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

#app_email_from = kallithea-noreply@example.com

<%text>## Subject prefix for application emails.</%text>

<%text>## A space between this prefix and the real subject is automatically added.</%text>

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

#email_prefix =

<%text>## Example:</%text>

#email_prefix = [Kallithea]

<%text>## Recipients for error emails and fallback recipients of application mails.</%text>

<%text>## Multiple addresses can be specified, space-separated.</%text>

<%text>## Only addresses are allowed, do not add any name part.</%text>

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

#email_to =

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

#email_to = admin@example.com

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

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

use = egg:Paste#http

<%text>## nr of worker threads to spawn</%text>

<%text>## max request before thread respawn</%text>

<%text>## option to use threads of process</%text>

use_threadpool = true

%elif http_server == 'waitress':

<%text>## WAITRESS ##</%text>

use = egg:waitress#main

<%text>## number of worker threads</%text>

<%text>## MAX BODY SIZE 100GB</%text>

max_request_body_size = 107374182400

<%text>## use poll instead of select, fixes fd limits, may not work on old</%text>

<%text>## windows systems.</%text>

#asyncore_use_poll = True

%elif http_server == 'gunicorn':

<%text>## GUNICORN ##</%text>

use = egg:gunicorn#main

<%text>## number of process workers. You must set `instance_id = *` when this option</%text>

<%text>## is set to more than one worker</%text>

workers = 1

<%text>## process name</%text>

proc_name = kallithea

<%text>## type of worker class, one of sync, eventlet, gevent, tornado</%text>

<%text>## recommended for bigger setup is using of of other than sync one</%text>

worker_class = sync

max_requests = 1000

<%text>## ammount of time a worker can handle request before it gets killed and</%text>

<%text>## restarted</%text>

timeout = 3600

%elif http_server == 'uwsgi':

<%text>## UWSGI ##</%text>

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

[uwsgi]

socket = /tmp/uwsgi.sock

master = true

http = 127.0.0.1:5000

<%text>## set as deamon and redirect all output to file</%text>

#daemonize = ./uwsgi_kallithea.log

<%text>## master process PID</%text>

pidfile = ./uwsgi_kallithea.pid

<%text>## stats server with workers statistics, use uwsgitop</%text>

<%text>## for monitoring, `uwsgitop 127.0.0.1:1717`</%text>

stats = 127.0.0.1:1717

memory-report = true

<%text>## log 5XX errors</%text>

log-5xx = true

<%text>## Set the socket listen queue size.</%text>

listen = 256

<%text>## Gracefully Reload workers after the specified amount of managed requests</%text>

<%text>## (avoid memory leaks).</%text>

max-requests = 1000

<%text>## enable large buffers</%text>

buffer-size = 65535

<%text>## socket and http timeouts ##</%text>

http-timeout = 3600

socket-timeout = 3600

<%text>## Log requests slower than the specified number of milliseconds.</%text>

log-slow = 10

<%text>## Exit if no app can be loaded.</%text>

need-app = true

<%text>## Set lazy mode (load apps in workers instead of master).</%text>

lazy = true

<%text>## scaling ##</%text>

<%text>## set cheaper algorithm to use, if not set default will be used</%text>

cheaper-algo = spare

<%text>## minimum number of workers to keep at all times</%text>

cheaper = 1

<%text>## number of workers to spawn at startup</%text>

cheaper-initial = 1

<%text>## maximum number of workers that can be spawned</%text>

workers = 4

<%text>## how many workers should be spawned at a time</%text>

cheaper-step = 1

%endif

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

host = ${host}

port = ${port}

<%text>## middleware for hosting the WSGI application under a URL prefix</%text>

#[filter:proxy-prefix]

#use = egg:PasteDeploy#prefix

#prefix = /<your-prefix>

[app:main]

use = egg:kallithea

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

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

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

# Kallithea - Example config                                                   #

#                                                                              #

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

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

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

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

# Kallithea - config for tests:                                                #

# initial_repo_scan = true                                                     #

# vcs_full_cache = false                                                       #

# sqlalchemy and kallithea_test.sqlite                                         #

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