README.rst
215 lines
| 8.2 KiB
| text/x-rst
|
RstLexer
|
r4902 | ================ | ||
Kallithea README | ||||
================ | ||||
r2020 | ||||
|
r5433 | |||
r2020 | About | |||
----- | ||||
r572 | ||||
|
r4912 | **Kallithea** is a fast and powerful management tool for Mercurial_ and Git_ | ||
|
r4947 | with a built-in push/pull server, full text search and code-review. It works on | ||
http/https and has a built in permission/authentication system with the ability | ||||
to authenticate via LDAP or ActiveDirectory. Kallithea also provides simple API | ||||
so it's easy to integrate with existing external systems. | ||||
r1093 | ||||
|
r4947 | Kallithea is similar in some respects to GitHub_ or Bitbucket_, however | ||
Kallithea can be run as standalone hosted application on your own server. It is | ||||
open-source donationware and focuses more on providing a customised, | ||||
self-administered interface for Mercurial_ and Git_ repositories. Kallithea | ||||
works on Unix-like systems and Windows, and is powered by the vcs_ library | ||||
|
r4258 | created by Łukasz Balcerzak and Marcin Kuźmiński to uniformly handle multiple | ||
version control systems. | ||||
r572 | ||||
|
r4236 | Kallithea was forked from RhodeCode in July 2014 and has been heavily modified. | ||
|
r5425 | |||
r2020 | Installation | |||
------------ | ||||
|
r5433 | |||
|
r5401 | Kallithea requires Python_ 2.x and it is recommended to install it in a | ||
virtualenv_. Official releases of Kallithea can be installed with:: | ||||
r2020 | ||||
|
r4192 | pip install kallithea | ||
r2020 | ||||
|
r4902 | The development repository is kept very stable and used in production by the | ||
|
r5425 | developers -- you can do the same. | ||
r2020 | ||||
|
r4921 | Please visit https://docs.kallithea-scm.org/en/latest/installation.html for | ||
|
r4258 | more details. | ||
r2020 | ||||
r572 | ||||
Source code | ||||
----------- | ||||
|
r4947 | The latest sources can be obtained from | ||
https://kallithea-scm.org/repos/kallithea. | ||||
r1167 | ||||
|
r4902 | The issue tracker and a repository mirror can be found at Bitbucket_ on | ||
https://bitbucket.org/conservancy/kallithea. | ||||
r572 | ||||
r1167 | ||||
|
r5413 | Kallithea features | ||
r1093 | ------------------ | |||
r572 | ||||
|
r4947 | - Has its own middleware to handle Mercurial_ and Git_ protocol requests. Each | ||
request is authenticated and logged together with IP address. | ||||
- Built for speed and performance. You can make multiple pulls/pushes | ||||
simultaneously. Proven to work with thousands of repositories and users. | ||||
r3184 | - Supports http/https, LDAP, AD, proxy-pass authentication. | |||
|
r4947 | - Full permissions (private/read/write/admin) together with IP restrictions for | ||
each repository, additional explicit forking, repositories group and | ||||
repository creation permissions. | ||||
r3848 | - User groups for easier permission management. | |||
- Repository groups let you group repos and manage them easier. They come with | ||||
permission delegation features, so you can delegate groups management. | ||||
r3184 | - Users can fork other users repos, and compare them at any time. | |||
|
r4258 | - Built-in versioned paste functionality (Gist) for sharing code snippets. | ||
|
r4947 | - Integrates easily with other systems, with custom created mappers you can | ||
connect it to almost any issue tracker, and with a JSON-RPC API you can make | ||||
much more. | ||||
|
r4258 | - Built-in commit API lets you add, edit and commit files right from Kallithea | ||
r3184 | web interface using simple editor or upload binary files using simple form. | |||
|
r4947 | - Powerful pull request driven review system with inline commenting, changeset | ||
statuses, and notification system. | ||||
- Importing and syncing repositories from remote locations for Git_, Mercurial_ | ||||
and Subversion. | ||||
|
r4258 | - Mako templates let you customize the look and feel of the application. | ||
|
r4947 | - Beautiful diffs, annotations and source code browsing all colored by | ||
pygments. Raw diffs are made in Git-diff format for both VCS systems, | ||||
including Git_ binary-patches. | ||||
- Mercurial_ and Git_ DAG graphs and Flot-powered graphs with zooming and | ||||
statistics to track activity for repositories. | ||||
r847 | - Admin interface with user/permission management. Admin activity journal, logs | |||
pulls, pushes, forks, registrations and other actions made by all users. | ||||
r3224 | - Server side forks. It is possible to fork a project and modify it freely | |||
r3184 | without breaking the main repository. | |||
|
r4258 | - reST and Markdown README support for repositories. | ||
|
r4947 | - Full text search powered by Whoosh on the source files, commit messages, and | ||
file names. Built-in indexing daemons, with optional incremental index build | ||||
|
r4902 | (no external search servers required all in one application). | ||
|
r4258 | - Setup project descriptions/tags and info inside built in DB for easy, | ||
non-filesystem operations. | ||||
r3224 | - Intelligent cache with invalidation after push or project change, provides | |||
r1167 | high performance and always up to date data. | |||
|
r4902 | - RSS/Atom feeds, Gravatar support, downloadable sources as zip/tar/gz. | ||
- Optional async tasks for speed and performance using Celery_. | ||||
r3224 | - Backup scripts can do backup of whole app and send it over scp to desired | |||
|
r4902 | location. | ||
- Based on Pylons, SQLAlchemy, SQLite, Whoosh, vcs. | ||||
r253 | ||||
r552 | ||||
r572 | License | |||
------- | ||||
|
r4947 | **Kallithea** is released under the GPLv3 license. Kallithea is a `Software | ||
Freedom Conservancy`_ project and thus controlled by a non-profit organization. | ||||
No commercial entity can take ownership of the project and change the | ||||
direction. | ||||
|
r4902 | |||
|
r4947 | Kallithea started out as an effort to make sure the existing GPLv3 codebase | ||
would stay available under a legal license. Kallithea thus has to stay GPLv3 | ||||
compatible ... but we are also happy it is GPLv3 and happy to keep it that way. | ||||
A different license (such as AGPL) could perhaps help attract a different | ||||
community with a different mix of Free Software people and companies but we are | ||||
happy with the current focus. | ||||
r572 | ||||
|
r4902 | Community | ||
--------- | ||||
|
r4947 | **Kallithea** is maintained by its users who contribute the fixes they would | ||
|
r5425 | like to see. | ||
r676 | ||||
|
r4902 | Get in touch with the rest of the community: | ||
r676 | ||||
|
r5425 | - Join the mailing list users and developers -- see | ||
|
r4902 | http://lists.sfconservancy.org/mailman/listinfo/kallithea-general. | ||
r3224 | ||||
|
r4947 | - Use IRC and join #kallithea on FreeNode (irc.freenode.net) or use | ||
http://webchat.freenode.net/?channels=kallithea. | ||||
r3224 | ||||
|
r4912 | - Follow Kallithea on Twitter, **@KallitheaSCM**. | ||
r2020 | ||||
|
r4947 | - Issues can be reported at `issue tracker | ||
<https://bitbucket.org/conservancy/kallithea/issues>`_. | ||||
r2020 | ||||
|
r4902 | .. note:: | ||
|
r4947 | Please try to read the documentation before posting any issues, | ||
especially the **troubleshooting section** | ||||
r2020 | ||||
r796 | ||||
Online documentation | ||||
-------------------- | ||||
r572 | ||||
|
r4947 | Online documentation for the current version of Kallithea is available at | ||
https://pythonhosted.org/Kallithea/. Documentation for the current development | ||||
version can be found on https://docs.kallithea-scm.org/. | ||||
r2020 | ||||
|
r4902 | You can also build the documentation locally: go to ``docs/`` and run:: | ||
r572 | ||||
make html | ||||
|
r4955 | .. note:: You need to have Sphinx_ installed to build the | ||
documentation. If you don't have Sphinx_ installed you can | ||||
install it via the command: ``pip install sphinx`` . | ||||
r3224 | ||||
|
r4227 | |||
Converting from RhodeCode | ||||
------------------------- | ||||
|
r4947 | Currently, you have two options for working with an existing RhodeCode | ||
database: | ||||
|
r4979 | |||
- keep the database unconverted (intended for testing and evaluation) | ||||
- convert the database in a one-time step | ||||
|
r4227 | |||
|
r5413 | Maintaining interoperability | ||
|
r4227 | ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
r4902 | Interoperability with RhodeCode 2.2.X installations is provided so you don't | ||
|
r4227 | have to immediately commit to switching to Kallithea. This option will most | ||
likely go away once the two projects have diverged significantly. | ||||
|
r4258 | To run Kallithea on a RhodeCode database, run:: | ||
|
r4227 | |||
echo "BRAND = 'rhodecode'" > kallithea/brand.py | ||||
|
r4947 | This location will depend on where you installed Kallithea. If you installed | ||
via:: | ||||
|
r4227 | |||
python setup.py install | ||||
then you will find this location at | ||||
|
r4902 | ``$VIRTUAL_ENV/lib/python2.7/site-packages/Kallithea-0.1-py2.7.egg/kallithea``. | ||
|
r4227 | |||
|
r5413 | One-time conversion | ||
|
r4227 | ~~~~~~~~~~~~~~~~~~~ | ||
Alternatively, if you would like to convert the database for good, you can use | ||||
a helper script provided by Kallithea. This script will operate directly on the | ||||
database, using the database string you can find in your ``production.ini`` (or | ||||
``development.ini``) file. For example, if using SQLite:: | ||||
cd /path/to/kallithea | ||||
cp /path/to/rhodecode/rhodecode.db kallithea.db | ||||
pip install sqlalchemy-migrate | ||||
python kallithea/bin/rebranddb.py sqlite:///kallithea.db | ||||
|
r4902 | .. Note:: | ||
|
r4227 | |||
|
r4902 | If you started out using the branding interoperability approach mentioned | ||
above, watch out for stray brand.pyc after removing brand.py. | ||||
|
r4227 | |||
|
r5425 | |||
r869 | .. _virtualenv: http://pypi.python.org/pypi/virtualenv | |||
|
r4258 | .. _Python: http://www.python.org/ | ||
r869 | .. _Sphinx: http://sphinx.pocoo.org/ | |||
|
r4258 | .. _Mercurial: http://mercurial.selenic.com/ | ||
.. _Bitbucket: http://bitbucket.org/ | ||||
.. _GitHub: http://github.com/ | ||||
.. _Subversion: http://subversion.tigris.org/ | ||||
.. _Git: http://git-scm.com/ | ||||
.. _Celery: http://celeryproject.org/ | ||||
r3224 | .. _vcs: http://pypi.python.org/pypi/vcs | |||
|
r4902 | .. _Software Freedom Conservancy: http://sfconservancy.org/ | ||