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

Regardless of the installation method you may need to make sure you have

appropriate development packages installed, as installation of some of the

Kallithea dependencies requires a working C compiler and libffi library

headers. Depending on your configuration, you may also need to install

Git and development packages for the database of your choice.

For Debian and Ubuntu, the following command will ensure that a reasonable

set of dependencies is installed::

    sudo apt-get install build-essential git libffi-dev python3-dev

For Fedora and RHEL-derivatives, the following command will ensure that a

reasonable set of dependencies is installed::

    sudo yum install gcc git libffi-devel python3-devel

.. _installation-source:

Installation from repository source

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

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

repository, use the following commands in your bash shell::

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

        cd kallithea

        python3 -m venv ../kallithea-venv

        . ../kallithea-venv/bin/activate

        pip install --upgrade pip setuptools

        pip install --upgrade -e .

        python3 setup.py compile_catalog   # for translation of the UI

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

    python3 -m venv /srv/kallithea/venv

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

  basic requirements are up-to-date by running the following commands in your

  bash shell::

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

- 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 --upgrade kallithea

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

   the virtualenv too::

     pip install --upgrade kallithea python-ldap python-pam psycopg2

   This might require installation of development packages using your

   distribution's package manager.

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

  extract it and install from source by running::

    pip install --upgrade .

- This will install Kallithea together with all other required

  Python libraries into the activated virtualenv.

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

.. _overview:

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

Installation overview

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

Some overview and some details that can help understanding the options when

installing Kallithea.

1. **Prepare environment and external dependencies.**

    Kallithea needs:

    * A filesystem where the Mercurial and Git repositories can be stored.

    * A database where meta data can be stored.

    * A Python environment where the Kallithea application and its dependencies

      can be installed.

    * A web server that can host the Kallithea web application using the WSGI

      API.

2. **Install Kallithea software.**

    This makes the ``kallithea-cli`` command line tool available.

    Use ``kallithea-cli config-create`` to create a ``.ini`` file with database

    connection info, mail server information, configuration for the specified

    web server, etc.

    Use ``kallithea-cli db-create`` with the ``.ini`` file to create the

    database schema and insert the most basic information: the location of the

    repository store and an initial local admin user.

6. **Configure the web server.**

    The web server must invoke the WSGI entrypoint for the Kallithea software

    using the ``.ini`` file (and thus the database). This makes the web

    application available so the local admin user can log in and tweak the

    configuration further.

7. **Configure users.**

    The initial admin user can create additional local users, or configure how

    users can be created and authenticated from other user directories.

See the subsequent sections, the separate OS-specific instructions, and

:ref:`setup` for details on these steps.

Python environment

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

**Kallithea** is written entirely in Python_ and requires Python version

3.6 or higher.

Given a Python installation, there are different ways of providing the

environment for running Python applications. Each of them pretty much

corresponds to a ``site-packages`` directory somewhere where packages can be

installed.

Kallithea itself can be run from source or be installed, but even when running

from source, there are some dependencies that must be installed in the Python

environment used for running Kallithea.

- Packages *could* be installed in Python's ``site-packages`` directory ... but

  that would require running pip_ as root and it would be hard to uninstall or

  upgrade and is probably not a good idea unless using a package manager.

- Packages could also be installed in ``~/.local`` ... but that is probably

  only a good idea if using a dedicated user per application or instance.

- Finally, it can be installed in a virtualenv. That is a very lightweight

  "container" where each Kallithea instance can get its own dedicated and

  self-contained virtual environment.

We recommend using virtualenv for installing Kallithea.

Locale environment

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

In order to ensure a correct functioning of Kallithea with respect to non-ASCII

characters in user names, file paths, commit messages, etc., it is very

- for example by running::

    sudo -u postgres createuser 'kallithea' --pwprompt --createdb

For MariaDB/MySQL, run ``pip install mysqlclient`` to get the ``MySQLdb``

database driver. Make sure the database server is initialized and running. Make

sure you have a database user with password authentication with permissions to

create the database - for example by running::

    echo 'CREATE USER "kallithea"@"localhost" IDENTIFIED BY "password"' | sudo -u mysql mysql

    echo 'GRANT ALL PRIVILEGES ON `kallithea`.* TO "kallithea"@"localhost"' | sudo -u mysql mysql

Check and adjust ``sqlalchemy.url`` in your ``my.ini`` configuration file to use

this database.

Create the database, tables, and initial content by running the following

command::

    kallithea-cli db-create -c my.ini

This will first prompt you for a "root" path. This "root" path is the location

where Kallithea will store all of its repositories on the current machine. This

location must be writable for the running Kallithea application. Next,

``db-create`` will prompt you for a username and password for the initial admin

account it sets up for you.

The ``db-create`` values can also be given on the command line.

Example::

    kallithea-cli db-create -c my.ini --user=nn --password=secret --email=nn@example.com --repos=/srv/repos

The ``db-create`` command will create all needed tables and an

admin account. When choosing a root path you can either use a new

empty location, or a location which already contains existing

repositories. If you choose a location which contains existing

repositories Kallithea will add all of the repositories at the chosen

location to its database.  (Note: make sure you specify the correct

path to the root).

.. note:: It is also possible to use an existing database. For example,

          when using PostgreSQL without granting general createdb privileges to

          the PostgreSQL kallithea user, set ``sqlalchemy.url =

          postgresql://kallithea:password@localhost/kallithea`` and create the

          database like::

              sudo -u postgres createdb 'kallithea' --owner 'kallithea'

              kallithea-cli db-create -c my.ini --reuse

Running

^^^^^^^

You are now ready to use Kallithea. To run it using a gearbox web server,

simply execute::

    gearbox serve -c my.ini

- This command runs the Kallithea server. The web app should be available at

  http://127.0.0.1:5000. The IP address and port is configurable via the

  configuration file created in the previous step.

- Log in to Kallithea using the admin account created when running ``db-create``.

- The default permissions on each repository is read, and the owner is admin.

  Remember to update these if needed.

- In the admin panel you can toggle LDAP, anonymous, and permissions

  settings, as well as edit more advanced options on users and

  repositories.

Internationalization (i18n support)

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

The Kallithea web interface is automatically displayed in the user's preferred

language, as indicated by the browser. Thus, different users may see the

application in different languages. If the requested language is not available

(because the translation file for that language does not yet exist or is

incomplete), English is used.

If you want to disable automatic language detection and instead configure a

fixed language regardless of user preference, set ``i18n.enabled = false`` and

specify another language by setting ``i18n.lang`` in the Kallithea

configuration file.

Using Kallithea with SSH

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

Kallithea supports repository access via SSH key based authentication.

This means:

- repository URLs like ``ssh://kallithea@example.com/name/of/repository``

- all network traffic for both read and write happens over the SSH protocol on

  port 22, without using HTTP/HTTPS nor the Kallithea WSGI application

- encryption and authentication protocols are managed by the system's ``sshd``

  process, with all users using the same Kallithea system user (e.g.

  ``kallithea``) when connecting to the SSH server, but with users' public keys