##                                                                            ##

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

## If specifying credentials, make sure to use secure connections.

## Default: Send unencrypted unauthenticated mails to the specified smtp_server.

## For "SSL", use smtp_use_ssl = true and smtp_port = 465.

## For "STARTTLS", use smtp_use_tls = true and smtp_port = 587.

#smtp_server = smtp.example.com

#smtp_username =

#smtp_password =

#smtp_port = 25

#smtp_use_ssl = false

#smtp_use_tls = false

[server:main]

## nr of worker threads to spawn

#threadpool_workers = 1

## max request before thread respawn

#threadpool_max_requests = 100

## option to use threads of process

#use_threadpool = true

## WAITRESS ##

use = egg:waitress#main

## number of worker threads

threads = 1

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

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

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.url = sqlite:///%(here)s/kallithea.db?timeout=60

# POSTGRESQL

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

# MySQL

#sqlalchemy.url = mysql://user:pass@localhost/kallithea?charset=utf8

# see sqlalchemy docs for others

sqlalchemy.echo = false

sqlalchemy.pool_recycle = 3600

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

### ALEMBIC CONFIGURATION   ####

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

[alembic]

script_location = kallithea:alembic

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

### LOGGING CONFIGURATION   ####

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

[loggers]

[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

level = DEBUG

#formatter = generic

formatter = color_formatter

[handler_console_sql]

class = StreamHandler

args = (sys.stderr,)

#level = WARN

level = DEBUG

#formatter = generic

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

.. _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 on Our Own Kallithea (aka OOK) at

https://kallithea-scm.org/repos/kallithea/, our self-hosted instance

of Kallithea.

For now, we use Bitbucket_ for `pull requests`_ and `issue tracking`_. The

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

please use the `mailing list`_ or :ref:`IRC <readme>` 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

        pip install --upgrade pip setuptools

        pip install -e .

        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. Install the test

dependencies, then run the testsuite by invoking ``py.test`` from the

project root::

    pip install -r dev_requirements.txt

    py.test

Note that testing on Python 2.6 also requires ``unittest2``.

You can also use ``tox`` to run the tests with all supported Python versions

(currently Python 2.6--2.7).

When running tests, Kallithea uses `kallithea/tests/test.ini` and populates the

SQLite database specified there.

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

    KALLITHEA_WHOOSH_TEST_DISABLE=1 KALLITHEA_NO_TMP_PATH=1 py.test

    kill -9 $(cat test.pid)

In these commands, the following variables are used::

    KALLITHEA_WHOOSH_TEST_DISABLE=1 - skip whoosh index building and tests

    KALLITHEA_NO_TMP_PATH=1 - disable new temp path for tests, used mostly for testing_vcs_operations

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

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

are::

    -k EXPRESSION         only run tests which match the given substring

                          expression. An expression is a python evaluable

                          expression where all names are substring-matched

                          against test names and their parent classes. Example:

    -x, --exitfirst       exit instantly on first error or failed test.

    --lf                  rerun only the tests that failed at the last run (or

                          all if none failed)

    --ff                  run all tests but run the last failures first. This

                          may re-order tests and thus lead to repeated fixture

                          setup/teardown

    --pdb                 start the interactive Python debugger on errors.

    -s, --capture=no      don't capture stdout (any stdout output will be

                          printed immediately)

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.

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

Bitbucket, something hosted on your own Kallithea instance, or patches sent by

email to the `kallithea-general`_ mailing list.

When contributing via Bitbucket, please make your fork of

https://bitbucket.org/conservancy/kallithea/ `non-publishing`_ -- it is one of

the settings on "Repository details" page. This ensures your commits are in

"draft" phase and makes it easier for you to address feedback and for project

maintainers to integrate your changes.

.. _non-publishing: https://www.mercurial-scm.org/wiki/Phases#Publishing_Repository

Make sure to test your changes both manually and with the automatic tests

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

Database schema changes

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

Kallithea uses Alembic for :ref:`database migrations <upgrade_db>`

(upgrades and downgrades).

If you are developing a Kallithea feature that requires database schema

changes, you should make a matching Alembic database migration script:

1. :ref:`Create a Kallithea configuration and database <setup>` for testing

   the migration script, or use existing ``development.ini`` setup.

   Ensure that this database is up to date with the latest database

   schema *before* the changes you're currently developing. (Do not

   create the database while your new schema changes are applied.)

2. Create a separate throwaway configuration for iterating on the actual

   database changes::

   Edit the file to change database settings. SQLite is typically fine,

   but make sure to change the path to e.g. ``temp.db``, to avoid

   clobbering any existing database file.

3. Make your code changes (including database schema changes in ``db.py``).

4. After every database schema change, recreate the throwaway database

   to test the changes::

    rm temp.db

5. Once satisfied with the schema changes, auto-generate a draft Alembic

   script using the development database that has *not* been upgraded.

   (The generated script will upgrade the database to match the code.)

   ::

    alembic -c development.ini revision -m "area: add cool feature" --autogenerate

6. Edit the script to clean it up and fix any problems.

   Note that for changes that simply add columns, it may be appropriate

   to not remove them in the downgrade script (and instead do nothing),

   to avoid the loss of data. Unknown columns will simply be ignored by

   Kallithea versions predating your changes.

7. Run ``alembic -c development.ini upgrade head`` to apply changes to

   the (non-throwaway) database, and test the upgrade script. Also test

   downgrades.

   The included ``development.ini`` has full SQL logging enabled. If

   you're using another configuration file, you may want to enable it

   by setting ``level = DEBUG`` in section ``[handler_console_sql]``.

The Alembic migration script should be committed in the same revision as

the database schema (``db.py``) changes.

See the `Alembic documentation`__ for more information, in particular

the tutorial and the section about auto-generating migration scripts.

.. __: http://alembic.zzzcomputing.com/en/latest/

Troubleshooting

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

* If ``alembic --autogenerate`` responds "Target database is not up to

  date", you need to either first use Alembic to upgrade the database

  to the most recent version (before your changes), or recreate the

  database from scratch (without your schema changes applied).

    (As an alternative to IIS, SSO is also possible with for example Apache and

    mod_sspi.)

    Mercurial and Git do however by default not support SSO on the client side

    and will still require some other kind of authentication.

    (An extension like hgssoauthentication_ might solve that.)

.. note::

    For the best security, it is strongly recommended to only host the site over

    a secure connection, e.g. using TLS.

Prerequisites

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

Apart from the normal requirements for Kallithea, it is also necessary to get an

ISAPI-WSGI bridge module, e.g. isapi-wsgi.

Installation

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

The following assumes that your Kallithea is at ``c:\inetpub\kallithea``, and

will be served from the root of its own website. The changes to serve it in its

own virtual folder will be noted where appropriate.

Application pool

^^^^^^^^^^^^^^^^

Make sure that there is a unique application pool for the Kallithea application

with an identity that has read access to the Kallithea distribution.

The application pool does not need to be able to run any managed code. If you

are using a 32-bit Python installation, then you must enable 32-bit program in

the advanced settings for the application pool; otherwise Python will not be able

to run on the website and neither will Kallithea.

.. note::

    The application pool can be the same as an existing application pool,

    as long as the Kallithea requirements are met by the existing pool.

ISAPI handler

^^^^^^^^^^^^^

The ISAPI handler can be generated using::

This will generate a ``dispatch.py`` file in the current directory that contains

the necessary components to finalize an installation into IIS. Once this file

has been generated, it is necessary to run the following command due to the way

that ISAPI-WSGI is made::

    python2 dispatch.py install

This accomplishes two things: generating an ISAPI compliant DLL file,

``_dispatch.dll``, and installing a script map handler into IIS for the

``--virtualdir`` specified above pointing to ``_dispatch.dll``.

The ISAPI handler is registered to all file extensions, so it will automatically

be the one handling all requests to the specified virtual directory. When the website starts

middleware WSGI handler that Kallithea runs within and each HTTP request to the

site will be processed through this logic henceforth.

Authentication with Kallithea using IIS authentication modules

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The recommended way to handle authentication with Kallithea using IIS is to let

IIS handle all the authentication and just pass it to Kallithea.

.. note::

    As an alternative without SSO, you can also use LDAP authentication with

    Active Directory, see :ref:`ldap-setup`.

To move responsibility into IIS from Kallithea, we need to configure Kallithea

to let external systems handle authentication and then let Kallithea create the

user automatically. To do this, access the administration's authentication page

and enable the ``kallithea.lib.auth_modules.auth_container`` plugin. Once it is

added, enable it with the ``REMOTE_USER`` header and check *Clean username*.

Finally, save the changes on this page.

Switch to the administration's permissions page and disable anonymous access,

otherwise Kallithea will not attempt to use the authenticated user name. By

default, Kallithea will populate the list of users lazily as they log in. Either

disable external auth account activation and ensure that you pre-populate the

user database with an external tool, or set it to *Automatic activation of

external account*. Finally, save the changes.

The last necessary step is to enable the relevant authentication in IIS, e.g.

Windows authentication.

Troubleshooting

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

Typically, any issues in this setup will either be entirely in IIS or entirely

different options for finding issues exist: IIS' failed request tracking which

is great at finding issues until they exist inside Kallithea, at which point the

ISAPI-WSGI wrapper above uses ``win32traceutil``, which is part of ``pywin32``.

In order to dump output from WSGI using ``win32traceutil`` it is sufficient to

type the following in a console window::

    python2 -m win32traceutil

and any exceptions occurring in the WSGI layer and below (i.e. in the Kallithea

application itself) that are uncaught, will be printed here complete with stack

traces, making it a lot easier to identify issues.

.. _hgssoauthentication: https://bitbucket.org/domruf/hgssoauthentication

Step 7 -- Install Kallithea

^^^^^^^^^^^^^^^^^^^^^^^^^^^

In order to install Kallithea, you need to be able to run "pip install kallithea". It will use pip to install the Kallithea Python package and its dependencies.

Some Python packages use managed code and need to be compiled.

This can be done on Linux without any special steps. On Windows, you will need to install Microsoft Visual C++ compiler for Python 2.7.

Download and install "Microsoft Visual C++ Compiler for Python 2.7" from http://aka.ms/vcpython27

.. note::

  You can also install the dependencies using already compiled Windows binaries packages. A good source of compiled Python packages is http://www.lfd.uci.edu/~gohlke/pythonlibs/. However, not all of the necessary packages for Kallithea are on this site and some are hard to find, so we will stick with using the compiler.

In a command prompt type (adapting paths if necessary)::

  cd C:\Kallithea\Env\Scripts

  activate

  pip install --upgrade pip setuptools

The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar

(depending of your folder structure). Then type::

  pip install kallithea

.. note:: This will take some time. Please wait patiently until it is fully

          complete. Some warnings will appear. Don't worry, they are

          normal.

Step 8 -- Install Git (optional)

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Mercurial being a python package, was installed automatically when doing ``pip install kallithea``.

You need to install Git manually if you want Kallithea to be able to host Git repositories.

See http://git-scm.com/book/en/v2/Getting-Started-Installing-Git#Installing-on-Windows for instructions.

The location of the Git binaries (like ``c:\path\to\git\bin``) must be

added to the ``PATH`` environment variable so ``git.exe`` and other tools like

``gzip.exe`` are available.

Step 9 -- Configuring Kallithea

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Steps taken from `<setup.html>`_

You have to use the same command prompt as in Step 7, so if you closed

it, reopen it following the same commands (including the "activate"

one). When ready, type::

  cd C:\Kallithea\Bin

Then you must edit production.ini to fit your needs (IP address, IP

port, mail settings, database, etc.). `NotePad++`__ or a similar text

editor is recommended to properly handle the newline character

differences between Unix and Windows.

__ http://notepad-plus-plus.org/

For the sake of simplicity, run it with the default settings. After your edits (if any) in the previous command prompt, type::

.. warning:: This time a *new* database will be installed. You must

             follow a different process to later :ref:`upgrade <upgrade>`

             to a newer Kallithea version.

The script will ask you for confirmation about creating a new database, answer yes (y)

The script will ask you for the repository path, answer C:\\Kallithea\\Repos (or similar).

The script will ask you for the admin username and password, answer "admin" + "123456" (or whatever you want)

The script will ask you for admin mail, answer "admin@xxxx.com" (or whatever you want).

If you make a mistake and the script doesn't end, don't worry: start it again.

If you decided not to install Git, you will get errors about it that you can ignore.

Step 10 -- Running Kallithea

^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the previous command prompt, being in the C:\\Kallithea\\Bin folder, type::

Open your web server, and go to http://127.0.0.1:5000

It works!! :-)

Remark:

If it does not work the first time, Ctrl-C the CMD process and start it again. Don't forget the "http://" in Internet Explorer.

What this guide does not cover:

- Installing Celery

- Running Kallithea as a Windows Service. You can investigate here:

  - http://pypi.python.org/pypi/wsgisvc

  - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/

  - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service

- Using Apache. You can investigate here:

  - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4

Step 7 -- Install Kallithea

^^^^^^^^^^^^^^^^^^^^^^^^^^^

Finally, install Kallithea

Close previously opened command prompt/s, and open a Visual Studio 2008

Command Prompt (**IMPORTANT!!**). To do so, go to Start Menu, and then open

"Microsoft Visual C++ 2008 Express Edition" -> "Visual Studio Tools" ->

"Visual Studio 2008 Command Prompt"

.. note::

   64-bit: For 64-bit you need to modify the shortcut that is used to start the

   Visual Studio 2008 Command Prompt. Use right-mouse click to open properties.

Change commandline from::

%comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" x86

to::

%comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" amd64

In that CMD (loaded with VS2008 PATHs) type::

  cd C:\Kallithea\Env\Scripts (or similar)

  activate

  pip install --upgrade pip setuptools

The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar

(depending of your folder structure). Then type::

 pip install kallithea

(long step, please wait until fully complete)

Some warnings will appear, don't worry as they are normal.

Step 8 -- Configuring Kallithea

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

steps taken from http://packages.python.org/Kallithea/setup.html

You have to use the same Visual Studio 2008 command prompt as Step7, so

if you closed it reopen it following the same commands (including the

"activate" one). When ready, just type::

  cd C:\Kallithea\Bin

Then, you must edit production.ini to fit your needs (network address and

port, mail settings, database, whatever). I recommend using NotePad++

(free) or similar text editor, as it handles well the EndOfLine

character differences between Unix and Windows

(http://notepad-plus-plus.org/)

For the sake of simplicity lets run it with the default settings. After

your edits (if any), in the previous Command Prompt, type::

.. warning:: This time a *new* database will be installed. You must

             follow a different process to later :ref:`upgrade <upgrade>`

             to a newer Kallithea version.

The script will ask you for confirmation about creating a NEW database,

answer yes (y)

The script will ask you for repository path, answer C:\\Kallithea\\Repos

(or similar)

The script will ask you for admin username and password, answer "admin"

+ "123456" (or whatever you want)

The script will ask you for admin mail, answer "admin@xxxx.com" (or

whatever you want)

If you make some mistake and the script does not end, don't worry, start

it again.

Step 9 -- Running Kallithea

^^^^^^^^^^^^^^^^^^^^^^^^^^^

In the previous command prompt, being in the C:\\Kallithea\\Bin folder,

just type::

Open yout web server, and go to http://127.0.0.1:5000

It works!! :-)

Remark:

If it does not work first time, just Ctrl-C the CMD process and start it

again. Don't forget the "http://" in Internet Explorer

What this Guide does not cover:

- Installing Celery

- Running Kallithea as Windows Service. You can investigate here:

  - http://pypi.python.org/pypi/wsgisvc

  - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/

  - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service

- Using Apache. You can investigate here:

  - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4

Installation methods

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

Kallithea must be installed on a server. Kallithea is installed in a Python

environment so it can use packages that are installed there and make itself

available for other packages.

Two different cases will pretty much cover the options for how it can be

installed.

- The Kallithea source repository can be cloned and used -- it is kept stable and

  can be used in production. The Kallithea maintainers use the development

  branch in production. The advantage of installation from source and regularly

  updating it is that you take advantage of the most recent improvements. Using

  it directly from a DVCS also means that it is easy to track local customizations.

  Running ``pip install -e .`` in the source will use pip to install the

  necessary dependencies in the Python environment and create a

  ``.../site-packages/Kallithea.egg-link`` file there that points at the Kallithea

  source.

- Kallithea can also be installed from ready-made packages using a package manager.

  The official released versions are available on PyPI_ and can be downloaded and

  installed with all dependencies using ``pip install kallithea``.