=====

Setup

=====

Setting up Kallithea

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

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

following command to do so::

    kallithea-cli config-create 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. Extra settings can be specified like::

    kallithea-cli config-create my.ini host=8.8.8.8 "[handler_console]" formatter=color_formatter

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

the following command::

    kallithea-cli db-create -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 ``db-create`` will also prompt you for a username

and password for the initial admin account which ``db-create`` 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:: the given path for Mercurial_ repositories **must** be write

2. Create a backup of both database and configuration

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

You are of course strongly recommended to make backups regularly, but it

is *especially* important to make a full database and configuration

backup before performing a Kallithea upgrade.

Back up your configuration

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

Make a copy of your Kallithea configuration (``.ini``) file.

If you are using :ref:`rcextensions <customization>`, you should also

make a copy of the entire ``rcextensions`` directory.

Back up your database

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

If using SQLite, simply make a copy of the Kallithea database (``.db``)

file.

If using PostgreSQL, please consult the documentation for the ``pg_dump``

utility.

utility.

Look for ``sqlalchemy.url`` in your configuration file to determine

database type, settings, location, etc. If you were running Kallithea 0.3.x or

older, this was ``sqlalchemy.db1.url``.

3. Activate or recreate the Kallithea virtual environment (if any)

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

.. note::

    If you did not install Kallithea in a virtual environment, skip this step.

For major upgrades, e.g. from 0.3.x to 0.4.x, it is recommended to create a new

virtual environment, rather than reusing the old. For minor upgrades, e.g.

within the 0.4.x range, this is not really necessary (but equally fine).

To create a new virtual environment, please refer to the appropriate

installation page for details. After creating and activating the new virtual

environment, proceed with the rest of the upgrade process starting from the next

section.

To reuse the same virtual environment, first activate it, then verify that you

are using the correct environment by running::

Caching

-------

Tweak beaker cache settings in the ini file. The actual effect of that is

questionable.

.. note::

    Beaker has no upper bound on cache size and will never drop any caches. For

    memory cache, the only option is to regularly restart the worker process.

    For file cache, it must be cleaned manually, as described in the `Beaker

    documentation <https://beaker.readthedocs.io/en/latest/sessions.html#removing-expired-old-sessions>`_::

        find data/cache -type f -mtime +30 -print -exec rm {} \;

Database

--------

SQLite is a good option when having a small load on the system. But due to

locking issues with SQLite, it is not recommended to use it for larger

deployments.

increase. A tool like SQLAlchemyGrate_ can be used for migrating to another

database platform.

Horizontal scaling

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

Scaling horizontally means running several Kallithea instances and let them

share the load. That can give huge performance benefits when dealing with large

amounts of traffic (many users, CI servers, etc.). Kallithea can be scaled

horizontally on one (recommended) or multiple machines.

It is generally possible to run WSGI applications multithreaded, so that

several HTTP requests are served from the same Python process at once. That can

in principle give better utilization of internal caches and less process

overhead.

One danger of running multithreaded is that program execution becomes much more

complex; programs must be written to consider all combinations of events and

problems might depend on timing and be impossible to reproduce.

Kallithea can't promise to be thread-safe, just like the embedded Mercurial

backend doesn't make any strong promises when used as Kallithea uses it.

Instead, we recommend scaling by using multiple server processes.

<%text>##</%text>################################

<%text>##</%text>        LOGVIEW CONFIG        ##

<%text>##</%text>################################

logview.sqlalchemy = #faa

logview.pylons.templating = #bfb

logview.pylons.util = #eee

<%text>##</%text>#######################

<%text>##</%text>      DB CONFIG      ##

<%text>##</%text>#######################

%if database_engine == 'sqlite':

<%text>##</%text> SQLITE [default]

sqlalchemy.url = sqlite:///%(here)s/kallithea.db?timeout=60

%elif database_engine == 'postgres':

<%text>##</%text> POSTGRESQL

sqlalchemy.url = postgresql://user:pass@localhost/kallithea

%elif database_engine == 'mysql':

<%text>##</%text> MySQL

sqlalchemy.url = mysql://user:pass@localhost/kallithea?charset=utf8

%endif

<%text>##</%text> see sqlalchemy docs for other backends

sqlalchemy.pool_recycle = 3600

<%text>##</%text>##############################

<%text>##</%text>   ALEMBIC CONFIGURATION    ##

<%text>##</%text>##############################

[alembic]

script_location = kallithea:alembic

<%text>##</%text>##############################

<%text>##</%text>   LOGGING CONFIGURATION    ##

<%text>##</%text>##############################

[loggers]

keys = root, routes, kallithea, sqlalchemy, tg, gearbox, beaker, templates, whoosh_indexer, werkzeug, backlash

[handlers]

keys = console, console_color, console_color_sql, null

[formatters]