.. _index:

.. include:: ./../README.rst

Users Guide

-----------

**Installation:**

.. toctree::

   :maxdepth: 1

   installation

   installation_iis

   setup

**Usage**

.. toctree::

   :maxdepth: 1

   usage/general

   usage/git_support

   usage/performance

   usage/locking

   usage/statistics

   usage/backup

   usage/subrepos

   usage/debugging

   usage/troubleshooting

**Develop**

.. toctree::

   :maxdepth: 1

   contributing

   changelog

**API**

.. toctree::

   :maxdepth: 1

   api/api

   api/models

Other topics

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

* :ref:`genindex`

* :ref:`search`

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

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

.. _django: http://www.djangoproject.com/

.. _mercurial: http://mercurial.selenic.com/

.. _bitbucket: http://bitbucket.org/

.. _subversion: http://subversion.tigris.org/

.. _git: http://git-scm.com/

.. _celery: http://celeryproject.org/

.. _Sphinx: http://sphinx.pocoo.org/

.. _vcs: http://pypi.python.org/pypi/vcs

.. _installation:

``Kallithea`` is written entirely in Python. Before posting any issues make

sure, your not missing any system libraries and using right version of

libraries required by Kallithea. There's also restriction in terms of mercurial

clients. Minimal version of hg client known working fine with Kallithea is

**1.6**. If you're using older client, please upgrade.

Installing Kallithea from PyPI (aka "Cheeseshop")

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

Kallithea requires python version 2.6 or higher.

The easiest way to install ``kallithea`` is to run::

    easy_install kallithea

Or::

    pip install kallithea

If you prefer to install Kallithea manually simply grab latest release from

http://pypi.python.org/pypi/Kallithea, decompress the archive and run::

    python setup.py install

Step by step installation example for Windows

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

:ref:`installation_win`

Step by step installation example for Linux

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

For installing Kallithea i highly recommend using separate virtualenv_. This

way many required by Kallithea libraries will remain sandboxed from your main

python and making things less problematic when doing system python updates.

Alternative very detailed installation instructions for Ubuntu Server with

celery, indexer and daemon scripts: https://gist.github.com/4546398

- Assuming you have installed virtualenv_ create a new virtual environment

  using virtualenv command::

    virtualenv --no-site-packages /opt/kallithea-venv

.. note:: Using ``--no-site-packages`` when generating your

   virtualenv is **very important**. This flag provides the necessary

   isolation for running the set of packages required by

   Kallithea.  If you do not specify ``--no-site-packages``,

   it's possible that Kallithea will not install properly into

   the virtualenv, or, even if it does, may not run properly,

   depending on the packages you've already got installed into your

   Python's "main" site-packages dir.

- this will install new virtualenv_ into `/opt/kallithea-venv`.

- Activate the virtualenv_ by running::

    source /opt/kallithea-venv/bin/activate

.. note:: If you're using UNIX, *do not* use ``sudo`` to run the

   ``virtualenv`` script.  It's perfectly acceptable (and desirable)

   to create a virtualenv as a normal user.

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

  filesystem. For example::

    mkdir /opt/kallithea

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

    easy_install kallithea

  or::

    pip install kallithea

- This will install Kallithea together with pylons and all other required

  python libraries into activated virtualenv

Requirements for Celery (optional)

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

In order to gain maximum performance

there are some third-party you must install. When Kallithea is used

together with celery you have to install some kind of message broker,

recommended one is rabbitmq_ to make the async tasks work.

Of course Kallithea works in sync mode also and then you do not have to install

any third party applications. However, using Celery_ will give you a large

Step by step Installation for Windows

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

Kallithea step-by-step install Guide for Windows

Target OS: Windows XP SP3 32bit English (Clean installation)

+ All Windows Updates until 24-may-2012

.. note::

   This installation is for 32bit systems, for 64bit windows you might need

   to download proper 64bit versions of the different packages(Windows Installer, Win32py extensions)

   plus some extra tweaks.

   These extra steps haven been marked as "64bit".

   Tested on Windows Server 2008 R2 SP1, 9-feb-2013.

   If you run into any 64bit related problems, please check these pages:

   - http://blog.victorjabur.com/2011/06/05/compiling-python-2-7-modules-on-windows-32-and-64-using-msvc-2008-express/

   - http://bugs.python.org/issue7511

Step1 - Install Visual Studio 2008 Express

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

Optional: You can also install MinGW, but VS2008 installation is easier.

Download "Visual C++ 2008 Express Edition with SP1" from:

http://www.microsoft.com/visualstudio/en-us/products/2008-editions/express

(if not found or relocated, google for "visual studio 2008 express" for

updated link)

You can also download full ISO file for offline installation, just

choose "All - Offline Install ISO image file" in the previous page and

choose "Visual C++ 2008 Express" when installing.

.. note::

   Using other versions of Visual Studio will lead to random crashes.

   You must use Visual Studio 2008!"

.. note::

   Silverlight Runtime and SQL Server 2008 Express Edition are not

   required, you can uncheck them

.. note::

   64bit: You also need to install the Microsoft Windows SDK for .NET 3.5 SP1 (.NET 4.0 won't work).

   Download from: http://www.microsoft.com/en-us/download/details.aspx?id=3138

.. note::

   64bit: You also need to copy and rename a .bat file to make the Visual C++ compiler work.

   I am not sure why this is not necessary for 32bit.

   Copy C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars64.bat to C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\amd64\vcvarsamd64.bat

Step2 - Install Python

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

Install Python 2.x.y (x = 6 or 7) x86 version (32bit). DO NOT USE A 3.x version.

Download Python 2.x.y from:

http://www.python.org/download/

Choose "Windows Installer" (32bit version) not "Windows X86-64

Installer". While writing this guide, the latest version was v2.7.3.

Remember the specific major and minor version installed, because it will

be needed in the next step. In this case, it is "2.7".

.. note::

   64bit: Just download and install the 64bit version of python.

Step3 - Install Win32py extensions

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

Download pywin32 from:

http://sourceforge.net/projects/pywin32/files/

- Click on "pywin32" folder

- Click on the first folder (in this case, Build 217, maybe newer when you try)

- Choose the file ending with ".win32-py2.x.exe" -> x being the minor

  version of Python you installed (in this case, 7)

  When writing this guide, the file was:

  http://sourceforge.net/projects/pywin32/files/pywin32/Build%20217/pywin32-217.win32-py2.7.exe/download

  .. note::

     64bit: Download and install the 64bit version.

     At the time of writing you can find this at:

     http://sourceforge.net/projects/pywin32/files/pywin32/Build%20218/pywin32-218.win-amd64-py2.7.exe/download

Step4 - Python BIN

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