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

        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-guidelies` below for configuring your fork correctly.

Contribution flow

Installation from repository source

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

To install Kallithea in a virtualenv_ using the stable branch of the development

repository, follow the instructions below::

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

        cd kallithea

        virtualenv ../kallithea-venv

        . ../kallithea-venv/bin/activate

        pip install --upgrade pip setuptools

        python2 setup.py compile_catalog   # for translation of the UI

You can now proceed to :ref:`setup`.

.. _installation-virtualenv:

Installing a released version in a virtualenv

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

It is highly recommended to use a separate virtualenv_ for installing Kallithea.

This way, all libraries required by Kallithea will be installed separately from your

  basic requirements are up-to-date by running::

    . /srv/kallithea/venv/bin/activate

    pip install --upgrade pip setuptools

.. note:: You can't use UNIX ``sudo`` to source the ``virtualenv`` script; it

   will "activate" a shell that terminates immediately. It is also perfectly

   acceptable (and desirable) to create a virtualenv as a normal user.

.. note:: Some dependencies are optional. If you need them, install them in

   the virtualenv too::

   This might require installation of development packages using your

   distribution's package manager.

- Make a folder for Kallithea data files, and configuration somewhere on the

  filesystem. For example::

    mkdir /srv/kallithea

- Go into the created directory and run this command to install Kallithea::

  Alternatively, download a .tar.gz from http://pypi.python.org/pypi/Kallithea,

  extract it and run::

- This will install Kallithea together with all other required

  Python libraries into the activated virtualenv.

You can now proceed to :ref:`setup`.

.. _installation-without-virtualenv:

Installing a released version without virtualenv

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

Please refer to the instructions for the installation method you

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

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