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. You can run

the testsuite running ``nosetest`` from the project root, or if you use tox

run tox for python2.6-2.7 with multiple database test. When using `nosetests`

to change your testing enviroment.

    paster serve test.ini --pid-file=test.pid --daemon

    KALLITHEA_WHOOSH_TEST_DISABLE=1 KALLITHEA_NO_TMP_PATH=1 nosetests -x kallithea/tests/other/test_vcs_operations.py

    kill -9 $(cat test.pid)

Coding/contribution guidelines

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

Kallithea is GPLv3 and we assume all contributions are made by the

committer/contributor and under GPLv3 unless explicitly stated. We do care a

lot about preservation of copyright and license information for existing code

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

.. note::

   Firstly, it is recommended that you **always** perform a database and

   configuration backup before doing an upgrade.

   (These directions will use '{version}' to note that this is the version of

   Kallithea that these files were used with.  If backing up your Kallithea

   instance from version 0.1 to 0.2, the ``my.ini`` file could be

   backed up to ``my.ini.0-1``.)

then make a copy of the database file::

 service kallithea stop

 cp kallithea.db kallithea.db.{version}

Back up your configuration file::

 cp my.ini my.ini.{version}

Ensure that you are using the Python Virtual Environment that you'd originally

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

following command to do this::

    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

configuration file to use this other database. Kallithea currently supports

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.

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

  (Note: make sure you specify the correct path to the root).

  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

  eventually 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 the

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

  Remember to update these if needed.

- In the admin panel you can toggle LDAP, anonymous, permissions settings. As

  well as edit more advanced options on users and repositories

Optionally users can create `rcextensions` package that extends Kallithea

functionality. To do this simply execute::

    paster make-rcext my.ini

This will create `rcextensions` package in the same place that your `ini` file

lives. With `rcextensions` it's possible to add additional mapping for whoosh,

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

Please see the `__init__.py` file inside `rcextensions` package

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

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

Settings in Admin.

There are 4 built in hooks that cannot be changed (only enable/disable by

checkboxes on previos section).

To add another custom hook simply fill in first section with

<name>.<hook_type> and the second one with hook path. Example hooks

can be found at *kallithea.lib.hooks*.

Changing default encoding

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

It is configurable as `default_encoding` in the .ini file.

This affects many parts in Kallithea including user names, filenames, and

encoding of commit messages. In addition Kallithea can detect if `chardet`

library is installed. If `chardet` is detected Kallithea will fallback to it

when there are encode/decode errors.

Celery configuration

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

Celery is configured in the Kallithea ini configuration files.

Simply set use_celery=true in the ini file then add / change the configuration

    fileConfig(ini)

    from paste.deploy import loadapp

    application = loadapp('config:' + ini)

Other configuration files

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

Some example init.d scripts can be found in init.d directory: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/

.. _virtualenv: http://pypi.python.org/pypi/virtualenv

.. _python: http://www.python.org/

.. _celery: http://celeryproject.org/

.. _rabbitmq: http://www.rabbitmq.com/

.. _python-ldap: http://www.python-ldap.org/

.. _mercurial-server: http://www.lshift.net/mercurial-server.html

.. _PublishingRepositories: http://mercurial.selenic.com/wiki/PublishingRepositories