.. _setup:

=====

Setup

=====

Setting up Kallithea

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

First, you will need to create a Kallithea configuration file. Run the

following command to do so::

    paster make-config Kallithea my.ini

This will create the file ``my.ini`` in the current directory. This

configuration file contains the various settings for Kallithea, e.g.,

proxy port, email settings, usage of static files, cache, Celery

settings, and logging.

Next, you need to create the databases used by Kallithea. It is recommended to

use PostgreSQL or SQLite (default). If you choose a database other than the

default, ensure you properly adjust the database URL in your ``my.ini``

configuration file to use this other database. Kallithea currently supports

PostgreSQL, SQLite and MySQL databases. Create the database by running

the following command::

    paster setup-db my.ini

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

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

entering this "root" path ``setup-db`` will also prompt you for a username

and password for the initial admin account which ``setup-db`` sets

up for you.

The setup process can be fully automated, example for lazy::

    paster setup-db my.ini --user=nn --password=secret --email=nn@your.kallithea.server --repos=/srv/repos

The ``setup-db`` command will create all of the 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:: the given path for Mercurial_ repositories **must** be write

          accessible for the application. It's very important since

          the Kallithea web interface will work without write access,

          but when trying to do a push it will fail with permission

          denied errors unless it has write access.

You are now ready to use Kallithea. To run it simply execute::

    paster serve my.ini

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

  http://127.0.0.1:5000. This ip and port is configurable via the my.ini

  file created in previous step

- Use the admin account you created above when running ``setup-db``

  to login to the web app.

- 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

Optionally users can create an ``rcextensions`` package that extends Kallithea

functionality. To do this simply execute::

    paster make-rcext my.ini

stats and add additional code into the push/pull/create/delete repo hooks,

for more details.

Using Kallithea with SSH

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

Kallithea currently only hosts repositories using http and https. (The addition

of ssh hosting is a planned future feature.) However you can easily use ssh in

parallel with Kallithea. (Repository access via ssh is a standard "out of

the box" feature of Mercurial_ and you can use this to access any of the

repositories that Kallithea is hosting. See PublishingRepositories_)

Kallithea repository structures are kept in directories with the same name

as the project. When using repository groups, each group is a subdirectory.

This allows you to easily use ssh for accessing repositories.

In order to use ssh you need to make sure that your web server and the users'

login accounts have the correct permissions set on the appropriate directories.

.. note:: These permissions are independent of any permissions you

          have set up using the Kallithea web interface.

If your main directory (the same as set in Kallithea settings) is for

example set to ``/srv/repos`` and the repository you are using is

named ``kallithea``, then to clone via ssh you should run::

    hg clone ssh://user@server.com//srv/repos/kallithea

Using other external tools such as mercurial-server_ or using ssh key-based

authentication is fully supported.

.. note:: In an advanced setup, in order for your ssh access to use

          the same permissions as set up via the Kallithea web

          interface, you can create an authentication hook to connect

          to the Kallithea db and run check functions for permissions

          against that.

Setting up Whoosh full text search

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

The whoosh index can be built by using the paster

command ``make-index``. To use ``make-index`` you must specify the configuration

file that stores the location of the index. You may specify the location of the

repositories (``--repo-location``).  If not specified, this value is retrieved

from the Kallithea database.

It is also possible to specify a comma separated list of

repositories (``--index-only``) to build index only on chooses repositories

skipping any other found in repos location

You may optionally pass the option ``-f`` to enable a full index rebuild. Without

the ``-f`` option, indexing will run always in "incremental" mode.

For an incremental index build use::

    paster make-index my.ini

For a full index rebuild use::

    paster make-index my.ini -f

Building an index for just selected repositories is possible with such command::

    paster make-index my.ini --index-only=vcs,kallithea

In order to do periodic index builds and keep your index always up to

date, it is recommended to use a crontab entry.  An example entry

might look like this::

    /path/to/python/bin/paster make-index /path/to/kallithea/my.ini

When using incremental mode (the default) whoosh will check the last

modification date of each file and add it to be reindexed if a newer file is

available. The indexing daemon checks for any removed files and removes them

from index.

If you want to rebuild the index from scratch, you can use the ``-f`` flag as above,

or in the admin panel you can check the "build from scratch" flag.

Setting up LDAP support

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

Kallithea supports LDAP authentication. In order

to use LDAP, you have to install the python-ldap_ package. This package is

available via pypi, so you can install it by running::

    pip install python-ldap

.. note:: ``python-ldap`` requires some libraries to be installed on

          your system, so before installing it check that you have at

          least the ``openldap`` and ``sasl`` libraries.

LDAP settings are located in the Admin->LDAP section.

# -*- coding: utf-8 -*-

# This program is free software: you can redistribute it and/or modify

# it under the terms of the GNU General Public License as published by

# the Free Software Foundation, either version 3 of the License, or

# (at your option) any later version.

#

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

#

# You should have received a copy of the GNU General Public License

# along with this program.  If not, see <http://www.gnu.org/licenses/>.

"""

kallithea.lib.paster_commands.make_rcextensions

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

make-rcext paster command for Kallithea

This file was forked by the Kallithea project in July 2014.

Original author and date, and relevant copyright and licensing information is below:

:created_on: Mar 6, 2012

:author: marcink

:copyright: (c) 2013 RhodeCode GmbH, and others.

:license: GPLv3, see LICENSE.md for more details.

"""

from __future__ import with_statement

import os

import sys

import pkg_resources

from kallithea.lib.utils import BasePasterCommand, ask_ok

# Add location of top level folder to sys.path

from os.path import dirname as dn

rc_path = dn(dn(dn(os.path.realpath(__file__))))

sys.path.append(rc_path)

class Command(BasePasterCommand):

    max_args = 1

    min_args = 1

    group_name = "Kallithea"

    takes_config_file = -1

    parser = BasePasterCommand.standard_parser(verbose=True)

    def command(self):

        from pylons import config

        here = config['here']

            'kallithea', os.path.join('config', 'rcextensions', '__init__.py')

        )

        ext_file = os.path.join(here, 'rcextensions', '__init__.py')

        if os.path.exists(ext_file):

            msg = ('Extension file already exists, do you want '

                   'to overwrite it ? [y/n]')

    def update_parser(self):

        pass