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