^extensions\.py$

^build$

^dist$

^docs/build$

^docs/_build$

^sql_dumps$

^fabfile\.py$

^venv$

^deps\.dot$

^deps\.svg$

^deps\.txt$

^\.pytype/

    Thomas De Schampheleire <thomas.de_schampheleire@nokia.com> 2014-2021

    Mads Kiilerich <mads@kiilerich.com> 2016-2021

    ssantos <ssantos@web.de> 2018-2021

    Private <adamantine.sword@gmail.com> 2019-2021

    Étienne Gilli <etienne@gilli.io> 2020-2021

    fresh <fresh190@protonmail.com> 2020-2021

    robertus <robertuss12@gmail.com> 2020-2021

    Eugenia Russell <eugenia.russell2019@gmail.com> 2021

    Michalis <michalisntovas@yahoo.gr> 2021

    vs <vsuhachev@yandex.ru> 2021

    Александр <akonn7@mail.ru> 2021

    Artem <kovalevartem.ru@gmail.com> 2020

    Tim Ooms <tatankat@users.noreply.github.com> 2020

- Importing and syncing repositories from remote locations for Git_ and

  Mercurial_.

pytest >= 4.6.6, < 5.5

Sphinx >= 1.8.0, < 3.1

isort == 5.1.2

pyflakes == 2.2.0

## Gearbox serve uses the Waitress web server ##

## avoid multi threading

## allow push of repos bigger than the default of 1 GB

#translate_forwarded_server = False

archive_cache_dir = %(here)s/data/tarballcache

## WSGI environment variable to get the IP address of the client (default REMOTE_ADDR)

#remote_addr_variable = HTTP_X_FORWARDED_FOR

## WSGI environment variable to get the protocol (http or https) of the client connection (default wsgi.url_scheme)

#url_scheme_variable = HTTP_X_FORWARDED_PROTO

## always pretend the client connected using HTTPS (default false)

#force_https = true

## use Strict-Transport-Security headers (default false)

#use_htsts = true

celery.worker_max_tasks_per_child = 100

#sqlalchemy.url = postgresql://kallithea:password@localhost/kallithea

#sqlalchemy.url = mysql://kallithea:password@localhost/kallithea?charset=utf8mb4

## Note: the mysql:// prefix should also be used for MariaDB

import kallithea

copyright = '2010-2021 by various authors, licensed as GPLv3.'

version = kallithea.__version__

release = kallithea.__version__

To get started with Kallithea development run the following commands in your

bash shell::

        python3 -m venv venv

        . venv/bin/activate

Internal dependencies

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

We try to keep the code base clean and modular and avoid circular dependencies.

Code should only invoke code in layers below itself.

Imports should import whole modules ``from`` their parent module, perhaps

``as`` a shortened name. Avoid imports ``from`` modules.

To avoid cycles and partially initialized modules, ``__init__.py`` should *not*

contain any non-trivial imports. The top level of a module should *not* be a

facade for the module functionality.

Common code for a module is often in ``base.py``.

The important part of the dependency graph is approximately linear. In the

following list, modules may only depend on modules below them:

``tests``

  Just get the job done - anything goes.

``bin/`` & ``config/`` & ``alembic/``

  The main entry points, defined in ``setup.py``. Note: The TurboGears template

  use ``config`` for the high WSGI application - this is not for low level

  configuration.

``controllers/``

  The top level web application, with TurboGears using the ``root`` controller

  as entry point, and ``routing`` dispatching to other controllers.

``templates/**.html``

  The "view", rendering to HTML. Invoked by controllers which can pass them

  anything from lower layers - especially ``helpers`` available as ``h`` will

  cut through all layers, and ``c`` gives access to global variables.

``lib/helpers.py``

  High level helpers, exposing everything to templates as ``h``. It depends on

  everything and has a huge dependency chain, so it should not be used for

  anything else. TODO.

``controllers/base.py``

  The base class of controllers, with lots of model knowledge.

``lib/auth.py``

  All things related to authentication. TODO.

``lib/utils.py``

  High level utils with lots of model knowledge. TODO.

``lib/hooks.py``

  Hooks into "everything" to give centralized logging to database, cache

  invalidation, and extension handling. TODO.

``model/``

  Convenience business logic wrappers around database models.

``model/db.py``

  Defines the database schema and provides some additional logic.

``model/scm.py``

  All things related to anything. TODO.

SQLAlchemy

  Database session and transaction in thread-local variables.

``lib/utils2.py``

  Low level utils specific to Kallithea.

``lib/webutils.py``

  Low level generic utils with awareness of the TurboGears environment.

TurboGears

  Request, response and state like i18n gettext in thread-local variables.

  External dependency with global state - usage should be minimized.

``lib/vcs/``

  Previously an independent library. No awareness of web, database, or state.

``lib/*``

  Various "pure" functionality not depending on anything else.

``__init__``

  Very basic Kallithea constants - some of them are set very early based on ``.ini``.

This is not exactly how it is right now, but we aim for something like that.

Especially the areas marked as TODO have some problems that need untangling.

Tests can be run on PostgreSQL like::

    sudo -u postgres createuser 'kallithea-test' --pwprompt  # password password

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

    REUSE_TEST_DB='postgresql://kallithea-test:password@localhost/kallithea-test' py.test

Tests can be run on MariaDB/MySQL like::

    echo "GRANT ALL PRIVILEGES ON \`kallithea-test\`.* TO 'kallithea-test'@'localhost' IDENTIFIED BY 'password'" | sudo -u mysql mysql

    TEST_DB='mysql://kallithea-test:password@localhost/kallithea-test?charset=utf8mb4' py.test

Contributions will be accepted in most formats -- such as commits hosted on your

own Kallithea instance, or patches sent by email to the `kallithea-general`_

mailing list.

- Kallithea can also be installed with plain pip - globally or with ``--user``

  or similar. 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. We recommend using virtualenv.

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

        python3 -m venv venv

        . venv/bin/activate

.. note::

   This will install all Python dependencies into the virtualenv. Kallithea

   itself will however only be installed as a pointer to the source location.

   The source clone must thus be kept in the same location, and it shouldn't be

   updated to other revisions unless you want to upgrade. Edits in the source

   tree will have immediate impact (possibly after a restart of the service).

You can now proceed to :ref:`prepare-front-end-files`.

- Don't install as root - install as a dedicated user like ``kallithea``.

  If necessary, create the top directory for the virtualenv (like

  ``/srv/kallithea/venv``) as root and assign ownership to the user.

  Make a parent folder for the virtualenv (and perhaps also Kallithea

  configuration and data files) such as ``/srv/kallithea``. Create the

  directory as root if necessary and grant ownership to the ``kallithea`` user.

- Create a new virtual environment, for example in ``/srv/kallithea/venv``,

  specifying the right Python binary::

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

  bash shell::

.. note:: You can't use UNIX ``sudo`` to source the ``activate`` script; it

   will "activate" a shell that terminates immediately.

- Install Kallithea in the activated virtualenv::

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

   extract it and install from source by running::

     pip install --upgrade .

You can now proceed to :ref:`prepare-front-end-files`.

.. _prepare-front-end-files:

Prepare front-end files

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

Finally, the front-end files with CSS and JavaScript must be prepared. This

depends on having some commands available in the shell search path: ``npm``

version 6 or later, and ``node.js`` (version 12 or later) available as

``node``. The installation method for these dependencies varies between

operating systems and distributions.

Prepare the front-end by running::

    kallithea-cli front-end-build

3. **Prepare front-end files**

    Some front-end files must be fetched or created using ``npm`` and ``node``

    tooling so they can be served to the client as static files.

4. **Create low level configuration file.**

5. **Populate the database.**

6. **Configure the web server.**

7. **Configure users.**

File system location

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

Kallithea can be installed in many different ways. The main parts are:

- A location for the Kallithea software and its dependencies. This includes

  the Python code, template files, and front-end code. After installation, this

  will be read-only (except when upgrading).

- A location for the ``.ini`` configuration file that tells the Kallithea

  instance which database to use (and thus also the repository location).

  After installation, this will be read-only (except when upgrading).

- A location for various data files and caches for the Kallithea instance. This

  is by default in a ``data`` directory next to the ``.ini`` file. This will

  have to be writable by the running Kallithea service.

- A database. The ``.ini`` file specifies which database to use. The database

  will be a separate service and live elsewhere in the filesystem if using

  PostgreSQL or MariaDB/MySQL. If using SQLite, it will by default live next to

  the ``.ini`` file, as ``kallithea.db``.

- A location for the repositories that are hosted by this Kallithea instance.

  This will have to be writable by the running Kallithea service. The path to

  this location will be configured in the database.

For production setups, one recommendation is to use ``/srv/kallithea`` for the

``.ini`` and ``data``, place the virtualenv in ``venv``, and use a Kallithea

clone in ``kallithea``. Create a ``kallithea`` user, let it own

``/srv/kallithea``, and run as that user when installing.

For simple setups, it is fine to just use something like a ``kallithea`` user

with home in ``/home/kallithea`` and place everything there.

For experiments, it might be convenient to run everything as yourself and work

inside a clone of Kallithea, with the ``.ini`` and SQLite database in the root

of the clone, and a virtualenv in ``venv``.

  ``kallithea.config.application:make_app`` as specified in ``setup.py``.)

.. _Waitress: https://docs.pylonsproject.org/projects/waitress/

.. _Gearbox: https://turbogears.readthedocs.io/en/latest/turbogears/gearbox.html

.. _mod_wsgi: https://modwsgi.readthedocs.io/

.. _uWSGI: https://uwsgi-docs.readthedocs.io/

Setting up a Kallithea instance

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

Some further details to the steps mentioned in the overview.

Create low level configuration file

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

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

configuration file is a ``.ini`` file that contains various low level settings

for Kallithea, e.g. configuration of how to use database, web server, email,

and logging.

Change to the desired directory (such as ``/srv/kallithea``) as the right user

and run the following command to create the file ``my.ini`` in the current

directory::

    kallithea-cli config-create my.ini http_server=waitress

To get a good starting point for your configuration, specify the http server

you intend to use. It can be ``waitress``, ``gearbox``, ``gevent``,

``gunicorn``, or ``uwsgi``. (Apache ``mod_wsgi`` will not use this

configuration file, and it is fine to keep the default http_server configuration

unused. ``mod_wsgi`` is configured using ``httpd.conf`` directives and a WSGI

wrapper script.)

Extra custom settings can be specified like::

Populate the database

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

Next, you need to create the databases used by Kallithea. Kallithea currently

supports PostgreSQL, SQLite and MariaDB/MySQL databases. It is recommended to

start out using SQLite (the default) and move to PostgreSQL if it becomes a

bottleneck or to get a "proper" database. MariaDB/MySQL is also supported.

For PostgreSQL, run ``pip install psycopg2`` to get the database driver. Make

sure the PostgreSQL server is initialized and running. Make sure you have a

database user with password authentication with permissions to create databases

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

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.

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

.. __: https://whoosh.readthedocs.io/

Custom Mercurial hooks can be managed in a similar way to that used in ``.hgrc`` files.