syntax: regexp

^rcextensions

^build

^dist/

^docs/build/

^docs/_build/

^data$

^sql_dumps/

^\.settings$

^\.project$

^\.pydevproject$

^\.coverage$

^kallithea\.db$

^test\.db$

^Kallithea\.egg-info$

^my\.ini$

^fabfile.py

^\.idea$

^\.cache$

/__pycache__$

Getting started

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

To get started with Kallithea 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 --upgrade -e .

        pip install --upgrade -r dev_requirements.txt

        gearbox make-config my.ini

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

        gearbox serve -c my.ini --reload &

        firefox http://127.0.0.1:5000/

If you plan to use Bitbucket_ for sending contributions, you can also fork

Kallithea on Bitbucket_ first (https://bitbucket.org/conservancy/kallithea) and

then replace the clone step above by a clone of your fork. In this case, please

see :ref:`contributing-guidelines` below for configuring your fork correctly.

Contribution flow

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

  With this method, Kallithea is installed in the Python environment as any

  other package, usually as a ``.../site-packages/Kallithea-X-py2.7.egg/``

  directory with Python files and everything else that is needed.

  (``pip install kallithea`` from a source tree will do pretty much the same

  but build the Kallithea package itself locally instead of downloading it.)

Web server

----------

Kallithea is (primarily) a WSGI_ application that must be run from a web

server that serves WSGI applications over HTTP.

Kallithea itself is not serving HTTP (or HTTPS); that is the web server's

responsibility. Kallithea does however need to know its own user facing URL

(protocol, address, port and path) for each HTTP request. Kallithea will

usually use its own HTML/cookie based authentication but can also be configured

to use web server authentication.

.. _setup:

=====

Setup

=====

Setting up Kallithea

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

First, you will need to create a Kallithea configuration file. Run the

following command to do so::

    gearbox make-config 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. Extra settings can be specified like::

originally used to install Kallithea.

If you originally installed using pip, it is as simple as::

    pip install --upgrade kallithea

If you originally installed from version control, it is as simple as::

    cd my-kallithea-clone

    hg pull -u

    pip install --upgrade -e .

5. Upgrade your configuration

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

Run the following command to create a new configuration (``.ini``) file::

    gearbox make-config new.ini

Then compare it with your old config file and see what changed.

.. note::

    Please always make sure your ``.ini`` files are up to date. Errors