README.rst
185 lines
| 7.4 KiB
| text/x-rst
|
RstLexer
Mads Kiilerich
|
r4902 | ================ | ||
Kallithea README | ||||
================ | ||||
r2020 | ||||
Mads Kiilerich
|
r5433 | |||
r2020 | About | |||
----- | ||||
r572 | ||||
Andrew Shadura
|
r4912 | **Kallithea** is a fast and powerful management tool for Mercurial_ and Git_ | ||
Sean Farley
|
r4947 | with a built-in push/pull server, full text search and code-review. It works on | ||
Christian Oyarzun
|
r7690 | HTTP/HTTPS and SSH, has a built-in permission/authentication system with the ability | ||
Sean Farley
|
r4947 | to authenticate via LDAP or ActiveDirectory. Kallithea also provides simple API | ||
so it's easy to integrate with existing external systems. | ||||
r1093 | ||||
Sean Farley
|
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 | ||||
Mads Kiilerich
|
r7652 | open-source and focuses more on providing a customised, | ||
Sean Farley
|
r4947 | self-administered interface for Mercurial_ and Git_ repositories. Kallithea | ||
Mads Kiilerich
|
r7652 | works on Unix-like systems and Windows. | ||
r572 | ||||
Bradley M. Kuhn
|
r4236 | Kallithea was forked from RhodeCode in July 2014 and has been heavily modified. | ||
Søren Løvborg
|
r5425 | |||
r2020 | Installation | |||
------------ | ||||
Mads Kiilerich
|
r5433 | |||
Mads Kiilerich
|
r8089 | Kallithea requires Python_ 3 and it is recommended to install it in a | ||
Mads Kiilerich
|
r8073 | virtualenv. Official releases of Kallithea can be installed with:: | ||
r2020 | ||||
Bradley M. Kuhn
|
r4192 | pip install kallithea | ||
r2020 | ||||
Mads Kiilerich
|
r4902 | The development repository is kept very stable and used in production by the | ||
Søren Løvborg
|
r5425 | developers -- you can do the same. | ||
r2020 | ||||
Thomas De Schampheleire
|
r4921 | Please visit https://docs.kallithea-scm.org/en/latest/installation.html for | ||
Andrew Shadura
|
r4258 | more details. | ||
r2020 | ||||
Robert Rauch
|
r5494 | There is also an experimental `Puppet module`_ for installing and setting up | ||
Kallithea. Currently, only basic functionality is provided, but it is still | ||||
enough to get up and running quickly, especially for people without Python | ||||
background. See | ||||
https://docs.kallithea-scm.org/en/latest/installation_puppet.html for further | ||||
information. | ||||
r572 | ||||
Source code | ||||
----------- | ||||
Sean Farley
|
r4947 | The latest sources can be obtained from | ||
https://kallithea-scm.org/repos/kallithea. | ||||
r1167 | ||||
Mads Kiilerich
|
r4902 | The issue tracker and a repository mirror can be found at Bitbucket_ on | ||
https://bitbucket.org/conservancy/kallithea. | ||||
r572 | ||||
r1167 | ||||
Mads Kiilerich
|
r5413 | Kallithea features | ||
r1093 | ------------------ | |||
r572 | ||||
Sean Farley
|
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. | ||||
Mads Kiilerich
|
r7652 | - Supports HTTP/HTTPS with LDAP, AD, or proxy-pass authentication. | ||
Christian Oyarzun
|
r7690 | - Supports SSH access with server-side public key management. | ||
Sean Farley
|
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. | |||
Andrew Shadura
|
r4258 | - Built-in versioned paste functionality (Gist) for sharing code snippets. | ||
Sean Farley
|
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. | ||||
Andrew Shadura
|
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. | |||
Sean Farley
|
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. | ||||
Andrew Shadura
|
r4258 | - Mako templates let you customize the look and feel of the application. | ||
Sean Farley
|
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. | ||||
Mads Kiilerich
|
r7652 | - Admin interface with user/permission management. Admin activity journal logs | ||
r847 | 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. | |||
Andrew Shadura
|
r4258 | - reST and Markdown README support for repositories. | ||
Sean Farley
|
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 | ||||
Mads Kiilerich
|
r4902 | (no external search servers required all in one application). | ||
Andrew Shadura
|
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. | |||
Mads Kiilerich
|
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 | |||
Mads Kiilerich
|
r4902 | location. | ||
Mads Kiilerich
|
r7652 | - Based on TurboGears2, SQLAlchemy, Whoosh, Bootstrap, and other open source | ||
libraries. | ||||
- Uses PostgreSQL, SQLite, or MariaDB/MySQL databases. | ||||
r253 | ||||
r552 | ||||
r572 | License | |||
------- | ||||
Sean Farley
|
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. | ||||
Mads Kiilerich
|
r4902 | |||
Sean Farley
|
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 | ||||
Mads Kiilerich
|
r4902 | Community | ||
--------- | ||||
Sean Farley
|
r4947 | **Kallithea** is maintained by its users who contribute the fixes they would | ||
Søren Løvborg
|
r5425 | like to see. | ||
r676 | ||||
Mads Kiilerich
|
r4902 | Get in touch with the rest of the community: | ||
r676 | ||||
Søren Løvborg
|
r5425 | - Join the mailing list users and developers -- see | ||
Mads Kiilerich
|
r4902 | http://lists.sfconservancy.org/mailman/listinfo/kallithea-general. | ||
r3224 | ||||
Sean Farley
|
r4947 | - Use IRC and join #kallithea on FreeNode (irc.freenode.net) or use | ||
http://webchat.freenode.net/?channels=kallithea. | ||||
r3224 | ||||
Andrew Shadura
|
r4912 | - Follow Kallithea on Twitter, **@KallitheaSCM**. | ||
r2020 | ||||
Sean Farley
|
r4947 | - Issues can be reported at `issue tracker | ||
<https://bitbucket.org/conservancy/kallithea/issues>`_. | ||||
r2020 | ||||
Mads Kiilerich
|
r4902 | .. note:: | ||
Sean Farley
|
r4947 | Please try to read the documentation before posting any issues, | ||
especially the **troubleshooting section** | ||||
r2020 | ||||
r796 | ||||
Online documentation | ||||
-------------------- | ||||
r572 | ||||
Sean Farley
|
r4947 | Online documentation for the current version of Kallithea is available at | ||
Thomas De Schampheleire
|
r7255 | https://docs.kallithea-scm.org/en/stable/. Documentation for the current development | ||
version can be found on https://docs.kallithea-scm.org/en/default/. | ||||
r2020 | ||||
Mads Kiilerich
|
r4902 | You can also build the documentation locally: go to ``docs/`` and run:: | ||
r572 | ||||
make html | ||||
Michael V. DePalatis
|
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 | ||||
Sean Farley
|
r4227 | |||
Søren Løvborg
|
r5976 | Migrating from RhodeCode | ||
------------------------ | ||||
Sean Farley
|
r4227 | |||
Søren Løvborg
|
r5976 | Kallithea 0.3.2 and earlier supports migrating from an existing RhodeCode | ||
installation. To migrate, install Kallithea 0.3.2 and follow the | ||||
instructions in the 0.3.2 README to perform a one-time conversion of the | ||||
database from RhodeCode to Kallithea, before upgrading to this version | ||||
of Kallithea. | ||||
Branko Majic
|
r5452 | |||
Søren Løvborg
|
r5425 | |||
Andrew Shadura
|
r4258 | .. _Python: http://www.python.org/ | ||
r869 | .. _Sphinx: http://sphinx.pocoo.org/ | |||
Andrew Shadura
|
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/ | ||||
Mads Kiilerich
|
r4902 | .. _Software Freedom Conservancy: http://sfconservancy.org/ | ||
Robert Rauch
|
r5494 | .. _Puppet module: https://forge.puppetlabs.com/rauch/kallithea | ||