.. _setup:

=====

Setup

=====

Setting up Kallithea

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

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

following command to do so::

    gearbox make-config 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

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

    gearbox setup-db -c 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-db`` values can also be given on the command line.

Example::

    gearbox setup-db -c my.ini --user=nn --password=secret --email=nn@example.com --repos=/srv/repos

The ``setup-db`` 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:: 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::

    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 ``setup-db``.

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

# -*- 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_config

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

make-config gearbox command for Kallithea

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

"""

import os

import sys

import uuid

import argparse

import mako.exceptions

TMPL = 'template.ini.mako'

here = os.path.dirname(os.path.abspath(__file__))

from kallithea.lib.paster_commands.common import BasePasterCommand

from kallithea.lib import inifile

class Command(BasePasterCommand):

    """Kallithea: Create a new config file

    make-config is part of a two-phase installation process (the

    second phase is setup-app). make-config creates a bare configuration

    file (possibly filling in defaults from the extra

    variables you give).

    """

    takes_config_file = False # at least not an existing one ...

    def take_action(self, args):

        _run(args)

    def get_parser(self, prog_name):

        parser = super(Command, self).get_parser(prog_name)

        parser.add_argument('config_file', nargs='?',

            help='application config file to write')

        parser.add_argument('custom', nargs=argparse.REMAINDER,

            help='custom values for the config file')

        parser.add_argument('--show-defaults', action='store_true',

            help="Show the default values that can be overridden")

        return parser

def _run(args):

    if args.config_file is None:

        if not args.show_defaults:

            raise ValueError("Missing argument: config_file")

    else:

        if args.show_defaults:

            raise ValueError("Can't specify both config_file and --show_defaults")

    mako_variable_values = {}

    for parameter in args.custom:

        parts = parameter.split('=', 1)

            key, value = parts

            mako_variable_values[key] = value

        else:

            raise ValueError("Invalid name=value parameter %r" % parameter)

    if args.show_defaults:

        for key, value in inifile.default_variables.items():

            value = mako_variable_values.get(key, value)

            print '%s=%s' % (key, value)

        sys.exit(0)

    # use default that cannot be replaced

    mako_variable_values.update({

        'uuid': lambda: uuid.uuid4().hex,

    })

    try:

        config_file = os.path.abspath(args.config_file)

        print 'Wrote new config file in %s' % config_file

    except Exception:

        print mako.exceptions.text_error_template().render()