include           Apache-License-2.0.txt

include           CONTRIBUTORS

include           COPYING

include           LICENSE-MERGELY.html

include           LICENSE.md

include           MIT-Permissive-License.txt

include           README.rst

include           development.ini

recursive-include docs *

recursive-include init.d *

recursive-include kallithea/alembic *

include           kallithea/bin/ldap_sync.conf

include           kallithea/bin/template.ini.mako

recursive-include kallithea/i18n *

recursive-include kallithea/public *

recursive-include kallithea/templates *

recursive-include kallithea/tests/fixtures *

recursive-include kallithea/tests/scripts *

include           kallithea/tests/test.ini

include           kallithea/tests/vcs/aconfig

https://kallithea-scm.org/repos/kallithea/, our self-hosted instance

of Kallithea.

For now, we use Bitbucket_ for `pull requests`_ and `issue tracking`_. The

issue tracker is for tracking bugs, not for support, discussion, or ideas --

please use the `mailing list`_ or :ref:`IRC <readme>` to reach the community.

We use Weblate_ to translate the user interface messages into languages other

than English. Join our project on `Hosted Weblate`_ to help us.

To register, you can use your Bitbucket or GitHub account. See :ref:`translations`

for more details.

Getting started

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

To get started with development::

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

        cd kallithea

        virtualenv ../kallithea-venv

        source ../kallithea-venv/bin/activate

        pip install --upgrade pip setuptools

        pip install -e .

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

        gearbox serve -c my.ini --reload &

        firefox http://127.0.0.1:5000/

You can also start out by forking https://bitbucket.org/conservancy/kallithea

on Bitbucket_ and create a local clone of your own fork.

Running tests

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

After finishing your changes make sure all tests pass cleanly. Install the test

dependencies, then run the testsuite by invoking ``py.test`` from the

project root::

    pip install -r dev_requirements.txt

    py.test

Note that testing on Python 2.6 also requires ``unittest2``.

You can also use ``tox`` to run the tests with all supported Python versions

(currently Python 2.6--2.7).

When running tests, Kallithea uses `kallithea/tests/test.ini` and populates the

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

Database schema changes

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

Kallithea uses Alembic for :ref:`database migrations <upgrade_db>`

(upgrades and downgrades).

If you are developing a Kallithea feature that requires database schema

changes, you should make a matching Alembic database migration script:

1. :ref:`Create a Kallithea configuration and database <setup>` for testing

   the migration script, or use existing ``development.ini`` setup.

   Ensure that this database is up to date with the latest database

   schema *before* the changes you're currently developing. (Do not

   create the database while your new schema changes are applied.)

2. Create a separate throwaway configuration for iterating on the actual

   database changes::

   Edit the file to change database settings. SQLite is typically fine,

   but make sure to change the path to e.g. ``temp.db``, to avoid

   clobbering any existing database file.

3. Make your code changes (including database schema changes in ``db.py``).

4. After every database schema change, recreate the throwaway database

   to test the changes::

    rm temp.db

    gearbox setup-db -c temp.ini --repos=/var/repos --user=doe --email doe@example.com --password=123456 --no-public-access --force-yes

    gearbox repo-scan -c temp.ini

5. Once satisfied with the schema changes, auto-generate a draft Alembic

   script using the development database that has *not* been upgraded.

   (The generated script will upgrade the database to match the code.)

   ::

    alembic -c development.ini revision -m "area: add cool feature" --autogenerate

6. Edit the script to clean it up and fix any problems.

          complete. Some warnings will appear. Don't worry, they are

          normal.

Step 8 -- Install Git (optional)

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

Mercurial being a python package, was installed automatically when doing ``pip install kallithea``.

You need to install Git manually if you want Kallithea to be able to host Git repositories.

See http://git-scm.com/book/en/v2/Getting-Started-Installing-Git#Installing-on-Windows for instructions.

The location of the Git binaries (like ``c:\path\to\git\bin``) must be

added to the ``PATH`` environment variable so ``git.exe`` and other tools like

``gzip.exe`` are available.

Step 9 -- Configuring Kallithea

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

Steps taken from `<setup.html>`_

You have to use the same command prompt as in Step 7, so if you closed

it, reopen it following the same commands (including the "activate"

one). When ready, type::

  cd C:\Kallithea\Bin

Then you must edit production.ini to fit your needs (IP address, IP

port, mail settings, database, etc.). `NotePad++`__ or a similar text

editor is recommended to properly handle the newline character

differences between Unix and Windows.

__ http://notepad-plus-plus.org/

For the sake of simplicity, run it with the default settings. After your edits (if any) in the previous command prompt, type::

  gearbox setup-db -c production.ini

.. warning:: This time a *new* database will be installed. You must

             follow a different process to later :ref:`upgrade <upgrade>`

             to a newer Kallithea version.

The script will ask you for confirmation about creating a new database, answer yes (y)

The script will ask you for the repository path, answer C:\\Kallithea\\Repos (or similar).

The script will ask you for the admin username and password, answer "admin" + "123456" (or whatever you want)

The script will ask you for admin mail, answer "admin@xxxx.com" (or whatever you want).

  cd C:\Kallithea\Env\Scripts (or similar)

  activate

  pip install --upgrade pip setuptools

The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar

(depending of your folder structure). Then type::

 pip install kallithea

(long step, please wait until fully complete)

Some warnings will appear, don't worry as they are normal.

Step 8 -- Configuring Kallithea

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

steps taken from http://packages.python.org/Kallithea/setup.html

You have to use the same Visual Studio 2008 command prompt as Step7, so

if you closed it reopen it following the same commands (including the

"activate" one). When ready, just type::

  cd C:\Kallithea\Bin

Then, you must edit production.ini to fit your needs (network address and

port, mail settings, database, whatever). I recommend using NotePad++

(free) or similar text editor, as it handles well the EndOfLine

character differences between Unix and Windows

(http://notepad-plus-plus.org/)

For the sake of simplicity lets run it with the default settings. After

your edits (if any), in the previous Command Prompt, type::

 gearbox setup-db -c production.ini

.. warning:: This time a *new* database will be installed. You must

             follow a different process to later :ref:`upgrade <upgrade>`

             to a newer Kallithea version.

The script will ask you for confirmation about creating a NEW database,

answer yes (y)

The script will ask you for repository path, answer C:\\Kallithea\\Repos

(or similar)

The script will ask you for admin username and password, answer "admin"

+ "123456" (or whatever you want)

The script will ask you for admin mail, answer "admin@xxxx.com" (or

whatever you want)

.. _setup:

=====

Setup

=====

Setting up Kallithea

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

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

following command to do so::

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

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

Kallithea isn't listed, activate the correct virtual environment.

See the appropriate installation page for details.

4. Install new version of Kallithea

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

Please refer to the instructions for the installation method you

originally used to install Kallithea.

If you originally installed using pip, it is as simple as::

    pip install --upgrade kallithea

If you originally installed from version control, it is as simple as::

    cd my-kallithea-clone

    hg pull -u

    pip install -e .

5. Upgrade your configuration

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

.. note::

    Please always make sure your ``.ini`` files are up to date. Errors

    can often be caused by missing parameters added in new versions.

.. _upgrade_db:

6. Upgrade your database

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

.. note::

    If you are *downgrading* Kallithea, you should perform the database

    migration step *before* installing the older version. (That is,

    always perform migrations using the most recent of the two versions

    you're migrating between.)

First, run the following command to see your current database version::

    alembic -c my.ini current

Typical output will be something like "9358dc3d6828 (head)", which is

the current Alembic database "revision ID". Write down the entire output

for troubleshooting purposes.

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

"""

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

"""

import os

import sys

import uuid

import argparse

from mako.template import Template

TMPL = 'template.ini.mako'

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

def _escape_split(text, sep):

    """

    Allows for escaping of the separator: e.g. arg='foo\, bar'

    It should be noted that the way bash et. al. do command line parsing, those

    single quotes are required. a shameless ripoff from fabric project.

    """

    escaped_sep = r'\%s' % sep

    if escaped_sep not in text:

        return text.split(sep)

    before, _, after = text.partition(escaped_sep)

    startlist = before.split(sep)  # a regular split is fine here

    unfinished = startlist[-1]

    startlist = startlist[:-1]

    # recurse because there may be more escaped separators

    endlist = _escape_split(after, sep)

    # finish building the escaped value. we use endlist[0] because the first

    # part of the string sent in recursion is the rest of the escaped value.

    unfinished += sep + endlist[0]

    return startlist + [unfinished] + endlist[1:]  # put together all the parts

    # defaults that can be overwritten by arguments

    tmpl_stored_args = {

        'http_server': 'waitress',

        'lang': 'en',

        'database_engine': 'sqlite',

        'host': '127.0.0.1',

        'port': 5000,

        'error_aggregation_service': None,

    }

        kwargs = {}

            kv = _escape_split(el, '=')

            if len(kv) == 2:

                k, v = kv

                kwargs[k] = v

        # update our template stored args

        tmpl_stored_args.update(kwargs)

    if args.show_defaults:

        for k,v in tmpl_stored_args.iteritems():

            print '%s=%s' % (k, v)

        sys.exit(0)

    try:

        # built in template

        tmpl_file = os.path.join(here, TMPL)

        with open(tmpl_file, 'rb') as f:

            tmpl_data = f.read().decode('utf-8')

            f.write(tmpl.encode('utf-8'))

    except Exception:

        from mako import exceptions

        print exceptions.text_error_template().render()

#!/usr/bin/env python2

"""

  development.ini

  kallithea/tests/test.ini

"""

import re

# the mako conditionals used in all other ini files and templates

selected_mako_conditionals = set([

    "database_engine == 'sqlite'",

    "http_server == 'waitress'",

    "error_aggregation_service == 'appenlight'",

    "error_aggregation_service == 'sentry'",

])

# the mako variables used in all other ini files and templates

mako_variable_values = {

    'host': '127.0.0.1',

    'port': '5000',

    'here': '%(here)s',

    'uuid()': '${app_instance_uuid}',

}

# files to be generated from the mako template

ini_files = [

    ('kallithea/tests/test.ini',

        '''

        Kallithea - config for tests:

        initial_repo_scan = true

        sqlalchemy and kallithea_test.sqlite

        custom logging

        The %(here)s variable will be replaced with the parent directory of this file

        ''',

        {

            '[server:main]': {

                'port': '4999',

            },

            '[app:main]': {

                'initial_repo_scan': 'true',

                'app_instance_uuid': 'test',

                'show_revision_number': 'true',

                'beaker.cache.sql_cache_short.expire': '1',

                'beaker.session.secret': '{74e0cd75-b339-478b-b129-07dd221def1f}',

                'cache_dir': '%(here)s/../../data/test/cache',

                'index_dir': '%(here)s/../../data/test/index',

                'archive_cache_dir': '%(here)s/../../data/test/tarballcache',

                'beaker.cache.data_dir': '%(here)s/../../data/test/cache/data',

                'beaker.cache.lock_dir': '%(here)s/../../data/test/cache/lock',

docs/usage/performance.rst

docs/usage/statistics.rst

docs/usage/troubleshooting.rst

docs/usage/vcs_support.rst

init.d/

init.d/celeryd-upstart.conf

init.d/kallithea-daemon-arch

init.d/kallithea-daemon-debian

init.d/kallithea-daemon-gentoo

init.d/kallithea-daemon-redhat

init.d/kallithea-upstart.conf

init.d/supervisord.conf

kallithea/

kallithea/__init__.py

kallithea/bin/

kallithea/bin/__init__.py

kallithea/bin/base.py

kallithea/bin/kallithea_api.py

kallithea/bin/kallithea_backup.py

kallithea/bin/kallithea_config.py

kallithea/bin/kallithea_gist.py

kallithea/bin/ldap_sync.conf

kallithea/bin/ldap_sync.py

kallithea/bin/rebranddb.py

kallithea/config/

kallithea/config/__init__.py

kallithea/config/conf.py

kallithea/config/environment.py

kallithea/config/middleware.py

kallithea/config/post_receive_tmpl.py

kallithea/config/pre_receive_tmpl.py

kallithea/config/rcextensions/

kallithea/config/rcextensions/__init__.py

kallithea/config/routing.py

kallithea/controllers/

kallithea/controllers/__init__.py

kallithea/controllers/admin/

kallithea/controllers/admin/__init__.py

kallithea/controllers/admin/admin.py

kallithea/controllers/admin/auth_settings.py

kallithea/controllers/admin/defaults.py

kallithea/controllers/admin/gists.py

kallithea/controllers/admin/my_account.py

kallithea/controllers/admin/notifications.py

kallithea/controllers/admin/permissions.py

kallithea/controllers/admin/repo_groups.py

kallithea/controllers/admin/repos.py

kallithea/controllers/admin/settings.py

kallithea/controllers/admin/user_groups.py

kallithea/controllers/admin/users.py

kallithea/controllers/api/

kallithea/lib/indexers/__init__.py

kallithea/lib/indexers/daemon.py

kallithea/lib/ipaddr.py

kallithea/lib/markup_renderer.py

kallithea/lib/middleware/

kallithea/lib/middleware/__init__.py

kallithea/lib/middleware/appenlight.py

kallithea/lib/middleware/https_fixup.py

kallithea/lib/middleware/pygrack.py

kallithea/lib/middleware/sentry.py

kallithea/lib/middleware/sessionmiddleware.py

kallithea/lib/middleware/simplegit.py

kallithea/lib/middleware/simplehg.py

kallithea/lib/middleware/wrapper.py

kallithea/lib/paster_commands/

kallithea/lib/paster_commands/__init__.py

kallithea/lib/paster_commands/cache_keys.py

kallithea/lib/paster_commands/cleanup.py

kallithea/lib/paster_commands/install_iis.py

kallithea/lib/paster_commands/ishell.py

kallithea/lib/paster_commands/make_index.py

kallithea/lib/paster_commands/make_rcextensions.py

kallithea/lib/paster_commands/repo_scan.py

kallithea/lib/paster_commands/setup_db.py

kallithea/lib/paster_commands/update_repoinfo.py

kallithea/lib/pidlock.py

kallithea/lib/profiler.py

kallithea/lib/rcmail/

kallithea/lib/rcmail/__init__.py

kallithea/lib/rcmail/exceptions.py

kallithea/lib/rcmail/message.py

kallithea/lib/rcmail/response.py

kallithea/lib/rcmail/smtp_mailer.py

kallithea/lib/rcmail/utils.py

kallithea/lib/recaptcha.py

kallithea/lib/timerproxy.py

kallithea/lib/utils.py

kallithea/lib/utils2.py

kallithea/lib/vcs/

kallithea/lib/vcs/__init__.py

kallithea/lib/vcs/backends/

kallithea/lib/vcs/backends/__init__.py

kallithea/lib/vcs/backends/base.py

kallithea/lib/vcs/backends/git/

kallithea/lib/vcs/backends/git/__init__.py

kallithea/lib/vcs/backends/git/changeset.py

kallithea/lib/vcs/backends/git/inmemory.py

kallithea/lib/vcs/backends/git/repository.py

    install_requires=requirements,

    classifiers=classifiers,

    data_files=data_files,

    packages=packages,

    include_package_data=True,

    message_extractors={'kallithea': [

            ('**.py', 'python', None),

            ('templates/**.mako', 'mako', {'input_encoding': 'utf-8'}),

            ('templates/**.html', 'mako', {'input_encoding': 'utf-8'}),

            ('public/**', 'ignore', None)]},

    zip_safe=False,

    entry_points="""

    [console_scripts]

    kallithea-api =    kallithea.bin.kallithea_api:main

    kallithea-gist =   kallithea.bin.kallithea_gist:main

    kallithea-config = kallithea.bin.kallithea_config:main

    [paste.app_factory]

    main = kallithea.config.middleware:make_app

    [paste.app_install]

    main = pylons.util:PylonsInstaller

    [gearbox.commands]

    setup-db=kallithea.lib.paster_commands.setup_db:Command

    cleanup-repos=kallithea.lib.paster_commands.cleanup:Command

    update-repoinfo=kallithea.lib.paster_commands.update_repoinfo:Command

    make-rcext=kallithea.lib.paster_commands.make_rcextensions:Command

    repo-scan=kallithea.lib.paster_commands.repo_scan:Command

    cache-keys=kallithea.lib.paster_commands.cache_keys:Command

    ishell=kallithea.lib.paster_commands.ishell:Command

    make-index=kallithea.lib.paster_commands.make_index:Command

    upgrade-db=kallithea.lib.dbmigrate:UpgradeDb

    celeryd=kallithea.lib.paster_commands.celeryd:Command

    install-iis=kallithea.lib.paster_commands.install_iis:Command

    """,

)