Kallithea README

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

About

-----

Installation

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

Kallithea requires Python_ 2.x and it is recommended to install it in a

virtualenv_. Official releases of Kallithea can be installed with::

API

===

Kallithea has a simple JSON RPC API with a single schema for calling all API

methods. Everything is available by sending JSON encoded http(s) requests to

``<your_server>/_admin/api``.

    result : "Pulled from `<reponame>`"

    error :  null

rescan_repos

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

               'removed': [<list of names of removed repos>]}"

    error :  null

invalidate_cache

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

    result : "Caches of repository `<reponame>`"

    error :  null

lock

----

             }

    error :  null

get_ip

------

    error :  null

get_user

--------

            }

    error:  null

get_users

---------

    kallithea-api create_user username:bent email:bent@example.com firstname:Bent lastname:Bentsen extern_type:ldap extern_name:uid=bent,dc=example,dc=com

update_user

-----------

            }

    error:  null

delete_user

-----------

            }

    error:  null

get_user_group

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

             }

    error : null

get_user_groups

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

              ]

    error : null

create_user_group

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

            }

    error:  null

add_user_to_user_group

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

            }

    error:  null

remove_user_from_user_group

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

            }

    error:  null

get_repo

--------

            }

    error:  null

get_repos

---------

            ]

    error:  null

get_repo_nodes

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

            ]

    error:  null

create_repo

-----------

            }

    error:  null

update_repo

-----------

            }

    error:  null

fork_repo

---------

            }

    error:  null

delete_repo

-----------

            }

    error:  null

grant_user_permission

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

            }

    error:  null

revoke_user_permission

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

            }

    error:  null

grant_user_group_permission

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

            }

    error:  null

revoke_user_group_permission

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

Kallithea project doesn't keep its changelog here.  We refer you to our `Mercurial logs`__.

.. __: https://kallithea-scm.org/repos/kallithea/changelog

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

for more details.

Getting started

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

                          printed immediately) [NOSE_NOCAPTURE]

    --failed              Run the tests that failed in the last test run.

Coding/contribution guidelines

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

.. _translations:

.. include:: ./../kallithea/i18n/how_to

"Roadmap"

---------

Kallithea Documentation

#######################

**Readme**

.. toctree::

* :ref:`genindex`

* :ref:`search`

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

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

.. _django: http://www.djangoproject.com/

.. _installation-source:

Installation from repository source

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

.. _installation-virtualenv:

Installing a released version in a virtualenv

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

.. _installation-without-virtualenv:

Installing a released version without virtualenv

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

You can now proceed to :ref:`setup`.

Upgrading Kallithea from Python Package Index (PyPI)

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

    For the best security, it is strongly recommended to only host the site over

    a secure connection, e.g. using TLS.

Prerequisites

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

Apart from the normal requirements for Kallithea, it is also necessary to get an

ISAPI-WSGI bridge module, e.g. isapi-wsgi.

Installation

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

    The application pool can be the same as an existing application pool,

    as long as the Kallithea requirements are met by the existing pool.

ISAPI handler

.............

The last necessary step is to enable the relevant authentication in IIS, e.g.

Windows authentication.

Troubleshooting

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

Installation and upgrade on Windows (7/Server 2008 R2 and newer)

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

First time install

::::::::::::::::::

To install on an older version of Windows, see `<installation_win_old.html>`_

Step 1 - Install Python

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

Remember the specific major and minor versions installed, because they will

be needed in the next step. In this case, it is "2.7".

Step 2 - Python BIN

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

Please substitute [your-python-path] with your Python installation

path. Typically this is ``C:\\Python27``.

Step 3 - Install pywin32 extensions

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

  http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win32-py2.7.exe/download

  (Win32)

Step 4 - Install pip

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

  SETX PATH "%PATH%;[your-python-path]\Scripts" /M

Step 5 - Kallithea folder structure

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

  C:\Kallithea\Env

  C:\Kallithea\Repos

Step 6 - Install virtualenv

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

  virtualenv C:\Kallithea\Env

Step 7 - Install Kallithea

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

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

          normal.

Step 8 - Install git (optional)

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

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

Step 9 - Configuring Kallithea

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

If you decided not to install git, you will get errors about it that you can ignore.

Step 10 - Running Kallithea

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

Installation and upgrade on Windows (XP/Vista/Server 2003/Server 2008)

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

First-time install

::::::::::::::::::

Step 1 - Install Visual Studio 2008 Express

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

Optional: You can also install MinGW, but VS2008 installation is easier.

Download "Visual C++ 2008 Express Edition with SP1" from:

   I am not sure why this is not necessary for 32-bit.

   Copy C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\vcvars64.bat to C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\bin\amd64\vcvarsamd64.bat

Step 2 -- Install Python

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

   64-bit: Just download and install the 64-bit version of python.

Step 3 -- Install Win32py extensions

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

     At the time of writing you can find this at:

     http://sourceforge.net/projects/pywin32/files/pywin32/Build%20218/pywin32-218.win-amd64-py2.7.exe/download

Step 4 -- Python BIN

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

  Please substitute [your-python-path] with your Python installation path.

  Typically: C:\\Python27

Step 5 -- Kallithea folder structure

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

  C:\Kallithea\Env

  C:\Kallithea\Repos

Step 6 -- Install virtualenv

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

(--no-site-packages is now the default behaviour of virtualenv, no need

to include it)

Step 7 -- Install Kallithea

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

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

Step 8 -- Configuring Kallithea

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

If you make some mistake and the script does not end, don't worry, start

it again.

Step 9 -- Running Kallithea

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

In the previous command prompt, being in the C:\\Kallithea\\Bin folder,

just type::

again. Don't forget the "http://" in Internet Explorer

What this Guide does not cover:

- Installing Celery

Installation overview

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

Some overview and some details that can help understanding the options when

installing Kallithea.

          to the Kallithea db and run check functions for permissions

          against that.

Setting up Whoosh full text search

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

It's also possible for an administrator to create accounts and configure their

permissions before the user logs in for the first time, using the :ref:`create-user` API.

Container-based authentication

''''''''''''''''''''''''''''''

to configure it to require authentication on the location configured for

Kallithea.

Proxy pass-through authentication

'''''''''''''''''''''''''''''''''

then change ``<someprefix>`` into your chosen prefix

Apache with mod_wsgi

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

.. __: https://kallithea-scm.org/repos/kallithea/files/tip/init.d/ .

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

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

.. _Mercurial: http://mercurial.selenic.com/

Just copy your .ini file, it contains all Kallithea settings.

Whoosh index

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

.. note:: First make sure you're using the latest version available.

Enable detailed debug

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

port (``smtp_port``), encryption settings (``smtp_use_tls`` or ``smtp_use_ssl``)

and/or specific authentication parameters (``smtp_auth``).

Application emails

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

optionally be prefixed with the value of ``email_prefix`` in the configuration

file.

Error emails

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

standard SMTP port (25). If you have a remote SMTP server with a different port,

you could set up a local forwarding SMTP server on port 25.

References

----------

- `Error Middleware (Pylons documentation) <http://pylons-webframework.readthedocs.org/en/latest/debugging.html#error-middleware>`_

- `ErrorHandler (Pylons modules documentation) <http://pylons-webframework.readthedocs.org/en/latest/modules/middleware.html#pylons.middleware.ErrorHandler>`_

.. _WebError: https://pypi.python.org/pypi/WebError

Kallithea and deletes a repository, you can easily restore such an action by

renaming the repository directory, removing the ``rm__<date>`` prefix.

File view: follow current branch

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

      that will separate regular user traffic from automated processes like CI

      servers or build bots.

.. _SQLAlchemyGrate: https://github.com/shazow/sqlalchemygrate

       #'git': 'Git repository',

   }

Git support

-----------

Web server with chunked encoding

````````````````````````````````

Large Git pushes require an HTTP server with support for

chunked encoding for POST. The Python web servers waitress_ and

gunicorn_ (Linux only) can be used. By default, Kallithea uses

Mercurial support

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

Working with Mercurial subrepositories

``````````````````````````````````````

This section explains how to use Mercurial subrepositories_ in Kallithea.

Example usage::

Next we can edit the subrepository data, and push back to Kallithea. This will

update both repositories.

.. _waitress: http://pypi.python.org/pypi/waitress

.. _gunicorn: http://pypi.python.org/pypi/gunicorn

.. _subrepositories: http://mercurial.aragost.com/kick-start/en/subrepositories/

Registered users may contribute to the existing languages, or request a new

language translations.

Translating using Weblate

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

format parameters, untranslated strings copied into the translation. Please perform

necessary corrections when they're needed, or override the false positives.

Merging translations from Weblate

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

which case it should be manually convinced it has to discard the commits it created by

using its administrative interface.

Manual creation of a new language translation

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

    python setup.py compile_catalog -l <new_language_code>

Updating translations

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

Edit the new updated translation file. Repeat all steps after `init_catalog` step from

new translation instructions

Testing translations

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