.. _index:

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

Kallithea Documentation

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

**Readme**

.. toctree::

   :maxdepth: 1

   readme

**Installation**

.. toctree::

   :maxdepth: 1

   overview

   installation

   installation_win

   installation_win_old

   installation_iis

   setup

   installation_puppet

**Usage**

.. toctree::

   :maxdepth: 1

   usage/general

   usage/vcs_support

   usage/locking

   usage/statistics

**Administrator's guide**

.. toctree::

   :maxdepth: 1

   usage/email

   usage/performance

   usage/backup

   usage/debugging

   usage/troubleshooting

   usage/customization

**Development**

.. toctree::

   :maxdepth: 1

   contributing

   changelog

**API**

.. toctree::

   :maxdepth: 1

   api/api

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:

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

Installation on Unix/Linux

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

The following describes three different ways of installing Kallithea:

- :ref:`installation-source`: The simplest way to keep the installation

  up-to-date and track any local customizations is to run directly from

  source in a Kallithea repository clone, preferably inside a virtualenv

  virtual Python environment.

- :ref:`installation-virtualenv`: If you prefer to only use released versions

  of Kallithea, the recommended method is to install Kallithea in a virtual

  Python environment using `virtualenv`. The advantages of this method over

  direct installation is that Kallithea and its dependencies are completely

  contained inside the virtualenv (which also means you can have multiple

  installations side by side or remove it entirely by just removing the

  virtualenv directory) and does not require root privileges.

- :ref:`installation-without-virtualenv`: The alternative method of installing

  a Kallithea release is using standard pip. The package will be installed in

  the same location as all other Python packages you have ever installed. As a

  result, removing it is not as straightforward as with a virtualenv, as you'd

  have to remove its dependencies manually and make sure that they are not

  needed by other packages.

.. _installation-source:

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

        source ../kallithea-venv/bin/activate

        pip install --upgrade pip setuptools

        pip install -e .

        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

main Python installation and other applications and things will be less

problematic when upgrading the system or Kallithea.

An additional benefit of virtualenv_ is that it doesn't require root privileges.

- Assuming you have installed virtualenv_, create a new virtual environment

  for example, in `/srv/kallithea/venv`, using the virtualenv command::

    virtualenv /srv/kallithea/venv

- Activate the virtualenv_ in your current shell session and make sure the

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

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

     pip install psycopg2

     pip install python-ldap

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

    pip install kallithea

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

  extract it and run::

    pip install .

- This will install Kallithea together with pylons_ and 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

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

For installation without virtualenv, 'just' use::

    pip install kallithea

Note that this method requires root privileges and will install packages

globally without using the system's package manager.

To install as a regular user in ``~/.local``, you can use::

    pip install --user kallithea

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

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

.. _pylons: http://www.pylonsproject.org/

.. _installation_win:

First time install

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

Target OS: Windows 7 and newer or Windows Server 2008 R2 and newer

Tested on Windows 8.1, Windows Server 2008 R2 and Windows Server 2012

To install on an older version of Windows, see `<installation_win_old.html>`_

Step 1 -- Install Python

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

Install Python 2.x.y (x = 6 or 7). Latest version is recommended. If you need another version, they can run side by side.

.. warning:: Python 3.x is not supported.

- Download Python 2.x.y from http://www.python.org/download/

- Choose and click on the version

- Click on "Windows X86-64 Installer" for x64 or "Windows x86 MSI installer" for Win32.

- Disable UAC or run the installer with admin privileges. If you chose to disable UAC, do not forget to reboot afterwards.

While writing this guide, the latest version was v2.7.9.

Remember the specific major and minor versions installed, because they will

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

Step 2 -- Python BIN

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

Add Python BIN folder to the path. This can be done manually (editing

"PATH" environment variable) or by using Windows Support Tools that

come pre-installed in Windows Vista/7 and later.

Open a CMD and type::

  SETX PATH "%PATH%;[your-python-path]" /M

Please substitute [your-python-path] with your Python installation

path. Typically this is ``C:\\Python27``.

Step 3 -- Install pywin32 extensions

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

Download pywin32 from:

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

- Click on "pywin32" folder

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

- Choose the file ending with ".amd64-py2.x.exe" (".win32-py2.x.exe"

  for Win32) where x is the minor version of Python you installed.

  When writing this guide, the file was:

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

  (x64)

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

  (Win32)

Step 4 -- Install pip

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

pip is a package management system for Python. You will need it to install Kallithea and its dependencies.

If you installed Python 2.7.9+, you already have it (as long as you ran the installer with admin privileges or disabled UAC).

If it was not installed or if you are using Python>=2.6,<2.7.9:

- Go to https://bootstrap.pypa.io

- Right-click on get-pip.py and choose Saves as...

- Run "python2 get-pip.py" in the folder where you downloaded get-pip.py (may require admin access).

.. note::

   See http://stackoverflow.com/questions/4750806/how-to-install-pip-on-windows

   for details and alternative methods.

Note that pip.exe will be placed inside your Python installation's

Scripts folder, which is likely not on your path. To correct this,

open a CMD and type::

  SETX PATH "%PATH%;[your-python-path]\Scripts" /M

Step 5 -- Kallithea folder structure

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

Create a Kallithea folder structure.

This is only an example to install Kallithea. Of course, you can

change it. However, this guide will follow the proposed structure, so

please later adapt the paths if you change them. Folders without

spaces are recommended.

Create the following folder structure::

  C:\Kallithea

  C:\Kallithea\Bin

  C:\Kallithea\Env

  C:\Kallithea\Repos

Step 6 -- Install virtualenv

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

.. note::

   A python virtual environment will allow for isolation between the Python packages of your system and those used for Kallithea.

   It is strongly recommended to use it to ensure that Kallithea does not change a dependency that other software uses or vice versa.

In a command prompt type::

  pip install virtualenv

Virtualenv will now be inside your Python Scripts path (C:\\Python27\\Scripts or similar).

To create a virtual environment, run::

  virtualenv C:\Kallithea\Env

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, it 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.

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

  paster make-config Kallithea production.ini

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

  paster setup-db production.ini

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

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

  paster serve production.ini

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

.. _installation_win_old:

First-time install

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

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

+ All Windows Updates until 24-may-2012

.. note::

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

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

   plus some extra tweaks.

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

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

   If you run into any 64-bit 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

Step 1 -- 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://download.microsoft.com/download/E/8/E/E8EEB394-7F42-4963-A2D8-29559B738298/VS2008ExpressWithSP1ENUX1504728.iso

(if not found or relocated, google for "visual studio 2008 express" for updated link. This link was taken from http://stackoverflow.com/questions/15318560/visual-c-2008-express-download-link-dead)

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

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

   64-bit: 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 32-bit.

   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

Step 2 -- Install Python

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

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

Download Python 2.x.y from:

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

Choose "Windows Installer" (32-bit 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::

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

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

     64-bit: Download and install the 64-bit 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

Step 4 -- Python BIN

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

Add Python BIN folder to the path

You have to add the Python folder to the path, you can do it manually

(editing "PATH" environment variable) or using Windows Support Tools

Create a Kallithea folder structure

This is only a example to install Kallithea, you can of course change

it. However, this guide will follow the proposed structure, so please

later adapt the paths if you change them. My recommendation is to use

folders with NO SPACES. But you can try if you are brave...

Create the following folder structure::

  C:\Kallithea

  C:\Kallithea\Bin

  C:\Kallithea\Env

  C:\Kallithea\Repos

Step 6 -- Install virtualenv

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

Install Virtual Env for Python

Navigate to: http://www.virtualenv.org/en/latest/index.html#installation

Right click on "virtualenv.py" file and choose "Save link as...".

Download to C:\\Kallithea (or whatever you want)

(the file is located at

https://raw.github.com/pypa/virtualenv/master/virtualenv.py)

Create a virtual Python environment in C:\\Kallithea\\Env (or similar). To

do so, open a CMD (Python Path should be included in Step3), navigate

where you downloaded "virtualenv.py", and write::

  python2 virtualenv.py C:\Kallithea\Env

(--no-site-packages is now the default behaviour of virtualenv, no need

to include it)

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

  paster make-config Kallithea production.ini

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

 paster setup-db production.ini

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

 paster serve production.ini

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