Mercurial > kallithea
changeset 4955:4e6dfdb3fa01
docs: English and consistency corrections
| author | Michael V. DePalatis <mike@depalatis.net> |
|---|---|
| date | Tue, 31 Mar 2015 22:15:38 +0200 |
| parents | 14f063657078 |
| children | 699689c31e0c |
| files | README.rst docs/api/api.rst docs/contributing.rst docs/installation.rst docs/installation_win.rst docs/setup.rst docs/usage/backup.rst docs/usage/debugging.rst docs/usage/general.rst docs/usage/git_support.rst docs/usage/locking.rst docs/usage/performance.rst docs/usage/statistics.rst docs/usage/subrepos.rst docs/usage/troubleshooting.rst |
| diffstat | 15 files changed, 357 insertions(+), 327 deletions(-) [+] |
line wrap: on
line diff
--- a/README.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/README.rst Tue Mar 31 22:15:38 2015 +0200 @@ -147,9 +147,9 @@ make html -(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``) +.. 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`` . Converting from RhodeCode
--- a/docs/api/api.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/api/api.rst Tue Mar 31 22:15:38 2015 +0200 @@ -5,7 +5,7 @@ === -Kallithea has a simple JSON RPC API with a single schema for calling all 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 . @@ -14,11 +14,11 @@ ++++++++++++++++++++++++ API access can also be turned on for each web view in Kallithea that is -decorated with the `@LoginRequired` decorator. Some views use -`@LoginRequired(api_access=True)` and are always available. By default only +decorated with the ``@LoginRequired`` decorator. Some views use +``@LoginRequired(api_access=True)`` and are always available. By default only RSS/ATOM feed views are enabled. Other views are only available if they have been white listed. Edit the -`api_access_controllers_whitelist` option in your .ini file and define views +``api_access_controllers_whitelist`` option in your .ini file and define views that should have API access enabled. For example, to enable API access to patch/diff raw file and archive:: @@ -30,7 +30,7 @@ FilesController:archivefile After this change, a Kallithea view can be accessed without login by adding a -GET parameter `?api_key=<api_key>` to url. +GET parameter ``?api_key=<api_key>`` to the URL. Exposing raw diffs is a good way to integrate with 3rd party services like code review, or build farms that could download archives. @@ -70,7 +70,7 @@ "error": "null"|<error_message> # JSON formatted error (if any) } -All responses from API will be `HTTP/1.0 200 OK`. If there is an error, +All responses from API will be ``HTTP/1.0 200 OK``. If there is an error, the reponse will have a failure description in *error* and *result* will be null. @@ -78,10 +78,10 @@ API client ++++++++++ -Kallithea comes with a `kallithea-api` command line tool providing a convenient +Kallithea comes with a ``kallithea-api`` command line tool providing a convenient way to call the JSON-RPC API. -For example, to call `get_repo`:: +For example, to call ``get_repo``:: kallithea-api --apihost=<your.kallithea.server.url> --apikey=<yourapikey> get_repo @@ -91,7 +91,8 @@ 'id': 75, 'result': None} -Oops, looks like we forgot to add an argument. Let's try again, now providing the repoid as parameter:: +Oops, looks like we forgot to add an argument. Let's try again, now +providing the ``repoid`` as a parameter:: kallithea-api get_repo repoid:myrepo @@ -101,11 +102,11 @@ 'id': 39, 'result': <json data...>} -To avoid specifying apihost and apikey every time, run:: +To avoid specifying ``apihost`` and ``apikey`` every time, run:: kallithea-api --save-config --apihost=<your.kallithea.server.url> --apikey=<yourapikey> -This will create a `~/.config/kallithea` with the specified hostname and apikey +This will create a ``~/.config/kallithea`` with the specified hostname and apikey so you don't have to specify them every time. @@ -139,8 +140,8 @@ rescan_repos ------------ -Rescan repositories. If remove_obsolete is set, -Kallithea will delete repos that are in database but not in the filesystem. +Rescan repositories. If ``remove_obsolete`` is set, +Kallithea will delete repos that are in the database but not in the filesystem. This command can only be executed using the api_key of a user with admin rights. INPUT:: @@ -163,7 +164,7 @@ invalidate_cache ---------------- -Invalidate cache for repository. +Invalidate the cache for a repository. This command can only be executed using the api_key of a user with admin rights, or that of a regular user with admin or write access to the repository. @@ -187,8 +188,8 @@ ---- Set the locking state on the given repository by the given user. -If param 'userid' is skipped, it is set to the id of the user who is calling this method. -If param 'locked' is skipped, the current lock state of the repository is returned. +If the param ``userid`` is skipped, it is set to the ID of the user who is calling this method. +If param ``locked`` is skipped, the current lock state of the repository is returned. This command can only be executed using the api_key of a user with admin rights, or that of a regular user with admin or write access to the repository. INPUT:: @@ -425,7 +426,7 @@ delete_user ----------- -Delete given user if such user exists. +Delete the given user if such a user exists. This command can only be executed using the api_key of a user with admin rights. @@ -555,8 +556,8 @@ add_user_to_user_group ---------------------- -Addsa user to a user group. If the user already is in that group, success will be -`false`. +Adds a user to a user group. If the user already is in that group, success will be +``false``. This command can only be executed using the api_key of a user with admin rights. @@ -585,7 +586,7 @@ --------------------------- Remove a user from a user group. If the user isn't in the given group, success will -be `false`. +be ``false``. This command can only be executed using the api_key of a user with admin rights. @@ -614,7 +615,7 @@ -------- Get an existing repository by its name or repository_id. Members will contain -either users_group or user associated to that repository. +either users_group or users associated to that repository. This command can only be executed using the api_key of a user with admin rights, or that of a regular user with at least read access to the repository. @@ -743,7 +744,7 @@ -------------- Return a list of files and directories for a given path at the given revision. -It's possible to specify ret_type to show only `files` or `dirs`. +It is possible to specify ret_type to show only ``files`` or ``dirs``. This command can only be executed using the api_key of a user with admin rights. @@ -775,7 +776,7 @@ create_repo ----------- -Create a repository. If repository name contains "/", all needed repository +Create a repository. If the repository name contains "/", all needed repository groups will be created. For example "foo/bar/baz" will create repository groups "foo", "bar" (with "foo" as parent), and create "baz" repository with "bar" as group. @@ -829,8 +830,8 @@ fork_repo --------- -Create a fork of given repo. If using celery, this will -return success message immidiatelly and fork will be created +Create a fork of the given repo. If using Celery, this will +return success message immediately and a fork will be created asynchronously. This command can only be executed using the api_key of a user with admin rights, or that of a regular user with fork permission and at least read access to the repository. @@ -869,7 +870,7 @@ Delete a repository. This command can only be executed using the api_key of a user with admin rights, or that of a regular user with admin access to the repository. -When `forks` param is set it's possible to detach or delete forks of the deleted repository. +When ``forks`` param is set it is possible to detach or delete forks of the deleted repository. INPUT:: @@ -895,7 +896,7 @@ grant_user_permission --------------------- -Grant permission for user on given repository, or update existing one if found. +Grant permission for a user on the given repository, or update the existing one if found. This command can only be executed using the api_key of a user with admin rights. @@ -923,7 +924,7 @@ revoke_user_permission ---------------------- -Revoke permission for user on given repository. +Revoke permission for a user on the given repository. This command can only be executed using the api_key of a user with admin rights. @@ -950,7 +951,7 @@ grant_user_group_permission --------------------------- -Grant permission for user group on given repository, or update +Grant permission for a user group on the given repository, or update the existing one if found. This command can only be executed using the api_key of a user with admin rights. @@ -979,7 +980,7 @@ revoke_user_group_permission ---------------------------- -Revoke permission for user group on given repository. +Revoke permission for a user group on the given repository. This command can only be executed using the api_key of a user with admin rights. INPUT::
--- a/docs/contributing.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/contributing.rst Tue Mar 31 22:15:38 2015 +0200 @@ -16,7 +16,7 @@ of Kallithea). For now, we use Bitbucket_ for `Pull Requests`_ and `Issue Tracker`_ services. The -issue tracker is for tracking bugs, not for "support", discussion or ideas - +issue tracker is for tracking bugs, not for support, discussion, or ideas - please use the `mailing list`_ to reach the community. We use Weblate_ to translate the user interface messages into languages other
--- a/docs/installation.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/installation.rst Tue Mar 31 22:15:38 2015 +0200 @@ -27,7 +27,7 @@ a Kallithea release is using standard pip. The package will be installed in the same location as all other Python packages you have ever installed. As a result, removing it is not as straightforward as with a virtualenv, as you'd - have to remove its dependencies manually and make sure that they not are + have to remove its dependencies manually and make sure that they are not needed by other packages. .. _installation-source: @@ -58,16 +58,13 @@ This way, all libraries required by Kallithea will be installed separately from your main Python installation and other applications and things will be less problematic when upgrading the system or Kallithea. -An additional benefit of virtualenv_ is that it doesn't require root privileges. +An additional benefit of virtualenv_ is that it doesn't require root privileges. - Assuming you have installed virtualenv_, create a new virtual environment - in for example `/srv/kallithea/venv` using the virtualenv command:: + for example, in `/srv/kallithea/venv`, using the virtualenv command:: virtualenv /srv/kallithea/venv -.. note:: Older versions of virtualenv required ``--no-site-packages`` to work - correctly. It should no longer be necessary. - - Activate the virtualenv_ in your current shell session by running:: source /srv/kallithea/venv/bin/activate @@ -81,7 +78,7 @@ mkdir /srv/kallithea -- Go into the created directory run this command to install kallithea:: +- Go into the created directory and run this command to install Kallithea:: pip install kallithea @@ -90,7 +87,7 @@ python setup.py install -- This will install Kallithea together with pylons and all other required +- This will install Kallithea together with pylons_ and all other required python libraries into the activated virtualenv. You can now proceed to :ref:`setup`. @@ -117,13 +114,13 @@ ----------------------------------------------------- .. note:: - Firstly, it is recommended that you **always** perform a database and + It is strongly 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 + 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``.) + backed up to ``my.ini.0-1``. If using a SQLite database, stop the Kallithea process/daemon/service, and @@ -138,13 +135,13 @@ cp my.ini my.ini.{version} -Ensure that you are using the Python Virtual Environment that you'd originally -installed Kallithea in:: +Ensure that you are using the Python virtual environment that you originally +installed Kallithea in by running:: pip freeze -will list all packages installed in the current environment. If Kallithea -isn't listed, change virtual environments to your venv location:: +This will list all packages installed in the current environment. If +Kallithea isn't listed, activate the correct virtual environment:: source /srv/kallithea/venv/bin/activate @@ -159,12 +156,12 @@ paster make-config Kallithea my.ini This will display any changes made by the new version of Kallithea to your -current configuration. It will try to perform an automerge. It's recommended -that you re-check the content after the automerge. +current configuration. It will try to perform an automerge. It is recommended +that you recheck the content after the automerge. .. note:: - Please always make sure your .ini files are up to date. Often errors are - caused by missing params added in new versions. + Please always make sure your .ini files are up to date. Errors can + often be caused by missing parameters added in new versions. It is also recommended that you rebuild the whoosh index after upgrading since @@ -182,9 +179,9 @@ .. note:: - DB schema upgrade library has some limitations and can sometimes fail if you try to - upgrade from older major releases. In such case simply run upgrades sequentially, eg. - upgrading from 0.1.X to 0.3.X should be done like that: 0.1.X. > 0.2.X > 0.3.X + The DB schema upgrade library has some limitations and can sometimes fail if you try to + upgrade from older major releases. In such a case simply run upgrades sequentially, e.g., + upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X You can always specify what version of Kallithea you want to install for example in pip `pip install Kallithea==0.2` @@ -208,3 +205,4 @@ .. _virtualenv: http://pypi.python.org/pypi/virtualenv .. _Python: http://www.python.org/ +.. _pylons: http://www.pylonsproject.org/
--- a/docs/installation_win.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/installation_win.rst Tue Mar 31 22:15:38 2015 +0200 @@ -19,14 +19,14 @@ Install Python 2.x.y (x = 6 or 7). Latest version is recommended. If you need another version, they can run side by side. - DO NOT USE A 3.x version. +.. warning:: Python 3.x is not supported. - Download Python 2.x.y from http://www.python.org/download/ - Choose and click on the version - Click on "Windows X86-64 Installer" for x64 or "Windows x86 MSI installer" for Win32. - Disable UAC or run the installer with admin privileges. If you chose to disable UAC, do not forget to reboot afterwards. -While writing this Guide, the latest version was v2.7.9. +While writing this guide, the latest version was v2.7.9. Remember the specific major and minor versions installed, because they will be needed in the next step. In this case, it is "2.7". @@ -34,18 +34,19 @@ Step 2 - Python BIN ------------------- -Add Python BIN folder to the path - -You have to add the Python folder to the path, you can do it manually (editing "PATH" environment variable) or using Windows Support Tools that came preinstalled in Vista/7 and later. +Add Python BIN folder to the path. This can be done manually (editing +"PATH" environment variable) or by using Windows Support Tools that +come pre-installed in Windows Vista/7 and later. Open a CMD and type:: SETX PATH "%PATH%;[your-python-path]" /M -Please substitute [your-python-path] with your Python installation path. Typically: C:\\Python27 +Please substitute [your-python-path] with your Python installation +path. Typically this is ``C:\\Python27``. -Step 3 - Install Win32py extensions +Step 3 - Install pywin32 extensions ----------------------------------- Download pywin32 from: @@ -53,10 +54,13 @@ - Click on "pywin32" folder - Click on the first folder (in this case, Build 219, maybe newer when you try) -- Choose the file ending with ".amd64-py2.x.exe" (".win32-py2.x.exe" for Win32) -> x being the minor version of Python you installed (in this case, 7). - When writing this Guide, the file was: - http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win-amd64-py2.7.exe/download (x64) - http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win32-py2.7.exe/download (Win32) +- Choose the file ending with ".amd64-py2.x.exe" (".win32-py2.x.exe" + for Win32) where x is the minor version of Python you installed. + When writing this guide, the file was: + http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win-amd64-py2.7.exe/download + (x64) + http://sourceforge.net/projects/pywin32/files/pywin32/Build%20219/pywin32-219.win32-py2.7.exe/download + (Win32) Step 4 - Install pip @@ -72,11 +76,14 @@ - Right-click on get-pip.py and choose Saves as... - Run "python get-pip.py" in the folder where you downloaded get-pip.py (may require admin access). -(See http://stackoverflow.com/questions/4750806/how-to-install-pip-on-windows for explanations or alternatives) +.. note:: -Note that pip.exe will be placed inside your Python installation's Scripts folder, which is likely not on your path. + See http://stackoverflow.com/questions/4750806/how-to-install-pip-on-windows + for details and alternative methods. -Open a CMD and type:: +Note that pip.exe will be placed inside your Python installation's +Scripts folder, which is likely not on your path. To correct this, +open a CMD and type:: SETX PATH "%PATH%;[your-python-path]\Scripts" /M @@ -86,7 +93,10 @@ Create a Kallithea folder structure. -This is only an example to install Kallithea. Of course, you can change it. However, this Guide will follow the proposed structure, so please later adapt the paths if you change them. Folders with NO SPACES are recommended. But you can try it if you are brave... +This is only an example to install Kallithea. Of course, you can +change it. However, this guide will follow the proposed structure, so +please later adapt the paths if you change them. Folders without +spaces are recommended. Create the following folder structure:: @@ -101,10 +111,7 @@ .. note:: A python virtual environment will allow for isolation between the Python packages of your system and those used for Kallithea. - It is strongly recommended to use it to ensure that Kallithea does not change a dependency that another software uses or vice versa. - If you are using your server (or VM) only for Kallithea, you can skip this step, at your own risk. - -Install Virtual Env for Python + It is strongly recommended to use it to ensure that Kallithea does not change a dependency that other software uses or vice versa. In a command prompt type:: @@ -120,7 +127,7 @@ Step 7 - Install Kallithea -------------------------- -In order to install Kallithea, you need to be able to run "pip install kallithea". It will use Python pip to install the Kallithea Python package and its dependencies. +In order to install Kallithea, you need to be able to run "pip install kallithea". It will use pip to install the Kallithea Python package and its dependencies. Some Python packages use managed code and need to be compiled. This can be done on Linux without any special steps. On Windows, you will need to install Microsoft Visual C++ compiler for Python 2.7. @@ -139,13 +146,14 @@ pip install kallithea -(Long step, please wait until fully complete) - -Some warnings will appear. Don't worry, they are normal. +.. note:: This will take some time. Please wait patiently until it is fully + complete. Some warnings will appear. Don't worry, they are + normal. Step 8 - (Optional) Install git ------------------------------- + Mercurial being a python package, it 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. @@ -158,28 +166,35 @@ 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:: +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 paster make-config Kallithea production.ini -Then, you must edit production.ini to fit your needs (IP address, IP port, mail settings, database, etc.) NotePad++ (free) or similar text editors are recommended, as they handle well the EndOfLine character differences between Unix and Windows (http://notepad-plus-plus.org/). +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. -For the sake of simplicity, run it with the default settings. After your edits (if any), in the previous Command Prompt, type:: +__ 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:: paster setup-db production.ini -(This time a NEW database will be installed. You must follow a different step to later UPGRADE to a newer Kallithea version) +.. warning:: This time a *new* database will be installed. You must + follow a different step to later *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 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 the 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 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) +The script will ask you for admin mail, answer "admin@xxxx.com" (or whatever you want). If you make a mistake and the script doesn't end, don't worry: start it again. @@ -201,7 +216,7 @@ If it does not work the first time, Ctrl-C the CMD process and start it again. Don't forget the "http://" in Internet Explorer. -What this Guide does not cover: +What this guide does not cover: - Installing Celery - Running Kallithea as a Windows Service. You can investigate here: @@ -226,14 +241,14 @@ Backup your production.ini file now. -Then, run:: +Then run:: paster make-config Kallithea production.ini Look for changes and update your production.ini accordingly. -Then, update the database:: +Next, update the database:: paster upgrade-db production.ini -Full steps in `<upgrade.html>`_ +More details can be found in `<upgrade.html>`_.
--- a/docs/setup.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/setup.rst Tue Mar 31 22:15:38 2015 +0200 @@ -9,19 +9,19 @@ -------------------- First, you will need to create a Kallithea configuration file. Run the -following command to do this:: +following command to do so:: 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. +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 +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:: @@ -34,46 +34,50 @@ and password for the initial admin account which ``setup-db`` sets up for you. -setup process can be fully automated, example for lazy:: +The 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 - choose a location which contains existing repositories Kallithea will - add all of the repositories at the chosen location to its database. - (Note: make sure you specify the correct path to the root). -- Note: the given path for Mercurial_ repositories **must** be write accessible - 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. +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 choose a location which contains existing +repositories Kallithea will add all of the repositories at the chosen +location to its database. (Note: make sure you specify the correct +path to the root). -You are now ready to use Kallithea, to run it simply execute:: +.. note:: the given path for Mercurial_ repositories **must** be write + accessible 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 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 +- This command runs the Kallithea server. The web app should be available at + http://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`` to login to the web app. - The default permissions on each repository is read, and the owner is admin. 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 +- In the admin panel you can toggle LDAP, anonymous, and permissions + settings, as well as edit more advanced options on users and + repositories -Optionally users can create `rcextensions` package that extends Kallithea +Optionally users can create an ``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. -For example for sending signals to build-bots such as Jenkins. -Please see the `__init__.py` file inside `rcextensions` package +This will create an ``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, +for example, for sending signals to build-bots such as Jenkins. +Please see the ``__init__.py`` file inside ``rcextensions`` package for more details. @@ -90,39 +94,41 @@ 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 +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.) + +.. note:: 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 -set to **/srv/repos** and the repository you are using is named `kallithea`, then -to clone via ssh you should run:: +If your main directory (the same as set in Kallithea settings) is for +example set to ``/srv/repos`` and the repository you are using is +named ``kallithea``, then to clone via ssh you should run:: hg clone ssh://user@server.com//srv/repos/kallithea -Using other external tools such as mercurial-server_ or using ssh key based +Using other external tools such as mercurial-server_ or using ssh key-based authentication is fully supported. -Note: In an advanced setup, in order for your ssh access to use the same -permissions as set up via the Kallithea web interface, you can create an -authentication hook to connect to the Kallithea db and runs check functions for -permissions against that. +.. note:: In an advanced setup, in order for your ssh access to use + the same permissions as set up via the Kallithea web + interface, you can create an authentication hook to connect + to the Kallithea db and run check functions for permissions + against that. Setting up Whoosh full text search ---------------------------------- -The whoosh index can be build by using the paster +The whoosh index can be built by using the paster command ``make-index``. To use ``make-index`` you must specify the configuration file that stores the location of the index. You may specify the location of the -repositories (`--repo-location`). If not specified, this value is retrieved +repositories (``--repo-location``). If not specified, this value is retrieved from the Kallithea database. It is also possible to specify a comma separated list of -repositories (`--index-only`) to build index only on chooses repositories +repositories (``--index-only``) to build index only on chooses repositories skipping any other found in repos location -You may optionally pass the option `-f` to enable a full index rebuild. Without -the `-f` option, indexing will run always in "incremental" mode. +You may optionally pass the option ``-f`` to enable a full index rebuild. Without +the ``-f`` option, indexing will run always in "incremental" mode. For an incremental index build use:: @@ -133,14 +139,14 @@ paster make-index my.ini -f -building index just for chosen repositories is possible with such command:: +Building an index for just selected repositories is possible with such command:: paster make-index my.ini --index-only=vcs,kallithea -In order to do periodical index builds and keep your index always up to date. -It's recommended to do a crontab entry for incremental indexing. -An example entry might look like this:: +In order to do periodic index builds and keep your index always up to +date, it is recommended to use a crontab entry. An example entry +might look like this:: /path/to/python/bin/paster make-index /path/to/kallithea/my.ini @@ -149,8 +155,8 @@ available. The indexing daemon checks for any removed files and removes them from index. -If you want to rebuild index from scratch, you can use the `-f` flag as above, -or in the admin panel you can check `build from scratch` flag. +If you want to rebuild the index from scratch, you can use the ``-f`` flag as above, +or in the admin panel you can check the "build from scratch" flag. Setting up LDAP support @@ -158,15 +164,15 @@ Kallithea supports LDAP authentication. In order to use LDAP, you have to install the python-ldap_ package. This package is -available via pypi, so you can install it by running +available via pypi, so you can install it by running:: pip install python-ldap -.. note:: - python-ldap requires some certain libs on your system, so before installing - it check that you have at least `openldap`, and `sasl` libraries. +.. note:: ``python-ldap`` requires some libraries to be installed on + your system, so before installing it check that you have at + least the ``openldap`` and ``sasl`` libraries. -LDAP settings are located in Admin->LDAP section. +LDAP settings are located in the Admin->LDAP section. Here's a typical LDAP setup:: @@ -190,7 +196,7 @@ Last Name Attribute = lastName E-mail Attribute = mail -If your user groups are placed in a Organisation Unit (OU) structure the Search Settings configuration differs:: +If your user groups are placed in an Organisation Unit (OU) structure, the Search Settings configuration differs:: Search settings Base DN = DC=host,DC=example,DC=org @@ -433,25 +439,26 @@ ------------------------------- Kallithea provides a simple integration with issue trackers. It's possible -to define a regular expression that will fetch issue id stored in commit -messages and replace that with an url to this issue. To enable this simply -uncomment following variables in the ini file:: +to define a regular expression that will fetch an issue id stored in a commit +messages and replace that with a URL to the issue. To enable this simply +uncomment the following variables in the ini file:: issue_pat = (?:^#|\s#)(\w+) issue_server_link = https://myissueserver.com/{repo}/issue/{id} issue_prefix = # -`issue_pat` is the regular expression describing which strings in +``issue_pat`` is the regular expression describing which strings in commit messages will be treated as issue references. A match group in parentheses should be used to specify the actual issue id. -The default expression matches issues in the format '#<number>', e.g. '#300'. +The default expression matches issues in the format ``#<number>``, e.g., ``#300``. -Matched issues are replaced with the link specified as `issue_server_link` -{id} is replaced with issue id, and {repo} with repository name. -Since the # is stripped away, `issue_prefix` is prepended to the link text. -`issue_prefix` doesn't necessarily need to be #: if you set issue -prefix to ISSUE- this will generate a URL in format:: +Matched issues are replaced with the link specified as +``issue_server_link`` ``{id}`` is replaced with issue id, and +``{repo}`` with the repository name. Since the # is stripped away, +``issue_prefix`` is prepended to the link text. ``issue_prefix`` doesn't +necessarily need to be ``#``: if you set issue prefix to ``ISSUE-`` this will +generate a URL in the format:: <a href="https://myissueserver.com/example_repo/issue/300">ISSUE-300</a> @@ -471,25 +478,25 @@ Hook management --------------- -Hooks can be managed in similar way to this used in .hgrc files. -To access hooks setting click `advanced setup` on Hooks section of Mercurial -Settings in Admin. +Hooks can be managed in similar way to that used in ``.hgrc`` files. +To access hooks setting click `advanced setup` in the `Hooks` section +of Mercurial 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*. +There are four built in hooks that cannot be changed (only enabled/disabled by +checkboxes in the previous section). +To add another custom hook simply fill in the first section with +``<name>.<hook_type>`` and the second one with hook path. Example hooks +can be found in ``kallithea.lib.hooks``. Changing default encoding ------------------------- By default, Kallithea uses UTF-8 encoding. -It is configurable as `default_encoding` in the .ini file. +This 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 +encoding of commit messages. In addition Kallithea can detect if the ``chardet`` +library is installed. If ``chardet`` is detected Kallithea will fallback to it when there are encode/decode errors. @@ -511,9 +518,9 @@ The use of Celery is configured in the Kallithea ini configuration file. To enable it, simply set:: - use_celery = true + use_celery = true -and add or change the celery.* and broker.* configuration variables. +and add or change the ``celery.*`` and ``broker.*`` configuration variables. Remember that the ini files use the format with '.' and not with '_' like Celery. So for example setting `BROKER_HOST` in Celery means setting @@ -536,10 +543,10 @@ Alternatively, you can use some special configuration settings to control directly which scheme/protocol Kallithea will use when generating URLs: -- With `https_fixup = true`, the scheme will be taken from the HTTP_X_URL_SCHEME, - HTTP_X_FORWARDED_SCHEME or HTTP_X_FORWARDED_PROTO HTTP header (default 'http'). -- With `force_https = true` the default will be 'https'. -- With `use_htsts = true`, it will set Strict-Transport-Security when using https. +- With ``https_fixup = true``, the scheme will be taken from the ``HTTP_X_URL_SCHEME``, + ``HTTP_X_FORWARDED_SCHEME`` or ``HTTP_X_FORWARDED_PROTO HTTP`` header (default ``http``). +- With ``force_https = true`` the default will be ``https``. +- With ``use_htsts = true``, it will set ``Strict-Transport-Security`` when using https. Nginx virtual host example -------------------------- @@ -671,7 +678,7 @@ </Location> Besides the regular apache setup you will need to add the following line -into [app:main] section of your .ini file:: +into ``[app:main]`` section of your .ini file:: filter-with = proxy-prefix @@ -682,7 +689,7 @@ prefix = /<someprefix> -then change <someprefix> into your chosen prefix +then change ``<someprefix>`` into your chosen prefix Apache's WSGI config -------------------- @@ -700,9 +707,9 @@ a2enmod wsgi - Create a wsgi dispatch script, like the one below. Make sure you - check the paths correctly point to where you installed Kallithea + check that the paths correctly point to where you installed Kallithea and its Python Virtual Environment. -- Enable the WSGIScriptAlias directive for the wsgi dispatch script, +- Enable the ``WSGIScriptAlias`` directive for the WSGI dispatch script, as in the following example. Once again, check the paths are correctly specified. @@ -714,7 +721,7 @@ WSGIScriptAlias / /srv/kallithea/dispatch.wsgi WSGIPassAuthorization On -Or if using a dispatcher wsgi script with proper virtualenv activation:: +Or if using a dispatcher WSGI script with proper virtualenv activation:: WSGIDaemonProcess kallithea processes=1 threads=4 WSGIScriptAlias / /srv/kallithea/dispatch.wsgi @@ -723,15 +730,15 @@ .. note:: When running apache as root, please make sure it doesn't run Kallithea as - root, for examply by adding: `user=www-data group=www-data` to the configuration. + root, for examply by adding: ``user=www-data group=www-data`` to the configuration. .. note:: If running Kallithea in multiprocess mode, - make sure you set `instance_id = \*` in the configuration so each process - gets it's own cache invalidationkey. + make sure you set ``instance_id = *`` in the configuration so each process + gets it's own cache invalidation key. -Example wsgi dispatch script:: +Example WSGI dispatch script:: import os os.environ["HGENCODING"] = "UTF-8" @@ -767,7 +774,8 @@ 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/ +Some example init.d scripts can be found in the ``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/
--- a/docs/usage/backup.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/usage/backup.rst Tue Mar 31 22:15:38 2015 +0200 @@ -13,8 +13,8 @@ Whoosh index ------------ -Whoosh index is located in **/data/index** directory where you installed -Kallithea ie. the same place where the ini file is located +The Whoosh index is located in the ``data/index`` directory where you installed +Kallithea, i.e., the same place where the ini file is located Database @@ -23,4 +23,4 @@ When using sqlite just copy kallithea.db. Any other database engine requires a manual backup operation. -Database backup will contain all gathered statistics +A database backup will contain all gathered statistics.
--- a/docs/usage/debugging.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/usage/debugging.rst Tue Mar 31 22:15:38 2015 +0200 @@ -4,27 +4,29 @@ Debugging Kallithea =================== -If you encountered problems with Kallithea here are some instructions how to -possibly debug them. +If you encounter problems with Kallithea, here are some instructions +on how to debug them. -** First make sure you're using the latest version available.** +.. note:: First make sure you're using the latest version available. Enable detailed debug --------------------- -Kallithea uses standard python logging modules to log it's output. -By default only loggers with INFO level are displayed. To enable full output -change `level = DEBUG` for all logging handlers in currently used .ini file. -This change will allow to see much more detailed output in the logfile or +Kallithea uses the standard Python ``logging`` module to log its output. +By default only loggers with ``INFO`` level are displayed. To enable full output +change ``level = DEBUG`` for all logging handlers in the currently used .ini file. +This change will allow you to see much more detailed output in the log file or console. This generally helps a lot to track issues. Enable interactive debug mode ----------------------------- -To enable interactive debug mode simply comment out `set debug = false` in -.ini file, this will trigger and interactive debugger each time there an -error in browser, or send a http link if error occured in the backend. This -is a great tool for fast debugging as you get a handy python console right -in the web view. ** NEVER ENABLE THIS ON PRODUCTION ** the interactive console -can be a serious security threat to you system. +To enable interactive debug mode simply comment out ``set debug = false`` in +the .ini file. This will trigger an interactive debugger each time +there is an error in the browser, or send a http link if an error occured in the backend. This +is a great tool for fast debugging as you get a handy Python console right +in the web view. + +.. warning:: NEVER ENABLE THIS ON PRODUCTION! The interactive console + can be a serious security threat to your system.
--- a/docs/usage/general.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/usage/general.rst Tue Mar 31 22:15:38 2015 +0200 @@ -8,48 +8,51 @@ Repository deleting ------------------- -Currently when admin/owner deletes a repository, Kallithea does not physically -delete a repository from filesystem, it renames it in a special way so it's -not possible to push,clone or access repository. It's worth a notice that, -even if someone will be given administrative access to Kallithea and will -delete a repository You can easy restore such action by restoring `rm__<date>` -from the repository name, and internal repository storage (.hg/.git). There -is also a special command for cleaning such archived repos:: +Currently when an admin or owner deletes a repository, Kallithea does +not physically delete said repository from the filesystem, but instead +renames it in a special way so that it is not possible to push, clone +or access repository. It is worth noting that even if someone will be +given administrative access to Kallithea and will delete a repository, +you can easy restore such an action by removing ``rm__<date>`` from +the repository name. There is also a special command for cleaning such +archived repos:: paster cleanup-repos --older-than=30d my.ini -This command will scan for archived repositories that are older than 30d, -display them and ask if you want to delete them (there's a --dont-ask flag also) -If you host big amount of repositories with forks that are constantly deleted -it's recommended that you run such command via crontab. +This command will scan for archived repositories that are older than +30 days, display them, and ask if you want to delete them (there is +a ``--dont-ask`` flag also) If you host a large amount of repositories with +forks that are constantly deleted it is recommended that you run such a +command via crontab. Follow current branch in file view ---------------------------------- In file view when this checkbox is checked the << and >> arrows will jump -to changesets within the same branch currently viewing. So for example -if someone is viewing files at 'beta' branch and marks `follow current branch` -checkbox the << and >> buttons will only show him revisions for 'beta' branch +to changesets within the same branch currently being viewed. So for example +if someone is viewing files in the ``beta`` branch and marks the `follow current branch` +checkbox the << and >> buttons will only show revisions for the `'beta`` branch. Compare view from changelog --------------------------- -Checkboxes in compare view allow users to view combined compare view. You can -only show the range between the first and last checkbox (no cherry pick). -Clicking more than one checkbox will activate a link in top saying -`Show selected changesets <from-rev> -> <to-rev>` clicking this will bring -compare view. In this view also it's possible to switch to combined compare. +Checkboxes in the compare view allow users to view a combined compare +view. You can only show the range between the first and last checkbox +(no cherry pick). Clicking more than one checkbox will activate a +link at the top saying ``Show selected changesets <from-rev> -> +<to-rev>``. Clicking this will activate the compare view. In this view +it is also possible to switch to combined compare. Compare view is also available from the journal on pushes having more than -one changeset +one changeset. Non changeable repository urls ------------------------------ -Due to complicated nature of repository grouping, often urls of repositories -can change. +Due to the complicated nature of repository grouping, URLs of repositories +can often change. example:: @@ -59,58 +62,56 @@ http://server.com/test_group/repo_name This can be an issue for build systems and any other hardcoded scripts, moving -repository to a group leads to a need for changing external systems. To -overcome this Kallithea introduces a non changable replacement url. It's -simply an repository ID prefixed with `_` above urls are also accessible as:: +a repository to a group leads to a need for changing external systems. To +overcome this Kallithea introduces a non-changable replacement URL. It's +simply a repository ID prefixed with ``_``. The above URLs are also accessible as:: http://server.com/_<ID> -Since ID are always the same moving the repository will not affect such url. -the _<ID> syntax can be used anywhere in the system so urls with repo_name -for changelogs, files and other can be exchanged with _<ID> syntax. +Since IDs are always the same, moving the repository will not affect +such a URL. the ``_<ID>`` syntax can be used anywhere in the system so +URLs with ``repo_name`` for changelogs and files can be exchanged +with the ``_<ID>`` syntax. Mailing ------- -When administrator will fill up the mailing settings in .ini files -Kallithea will send mails on user registration, or when Kallithea errors occur -on errors the mails will have a detailed traceback of error. - +When the administrator configures the mailing settings in .ini files +Kallithea will send mails on user registration, or when Kallithea +errors occur. Mails are also sent for code comments. If someone comments on a changeset mail is sent to all participants, the person who commited the changeset -(if present in Kallithea), and to all people mentioned with @mention system. +(if present in Kallithea), and to all people mentioned with the @mention system. Trending source files --------------------- -Trending source files are calculated based on pre defined dict of known -types and extensions. If You miss some extension or Would like to scan some -custom files it's possible to add new types in `LANGUAGES_EXTENSIONS_MAP` dict -located in `/kallithea/lib/celerylib/tasks.py` +Trending source files are calculated based on a pre-defined dict of known +types and extensions. If you miss some extension or would like to scan some +custom files, it is possible to add new types in the ``LANGUAGES_EXTENSIONS_MAP`` dict +located in ``kallithea/lib/celerylib/tasks.py``. Cloning remote repositories --------------------------- -Kallithea has an ability to clone remote repos from given remote locations. -Currently it support following options: +Kallithea has the ability to clone remote repos from given remote locations. +Currently it supports the following options: - hg -> hg clone - svn -> hg clone - git -> git clone -.. note:: - - - *`svn -> hg` cloning requires `hgsubversion` library to be installed.* +.. note:: svn -> hg cloning requires tge ``hgsubversion`` library to be installed. If you need to clone repositories that are protected via basic auth, you -might pass the url with stored credentials inside eg. -`http://user:passw@remote.server/repo`, Kallithea will try to login and clone -using given credentials. Please take a note that they will be stored as +might pass the url with stored credentials inside, e.g., +``http://user:passw@remote.server/repo``, Kallithea will try to login and clone +using the given credentials. Please take note that they will be stored as plaintext inside the database. Kallithea will remove auth info when showing the clone url in summary page. @@ -121,26 +122,28 @@ Visualisation settings in Kallithea settings view are extra customizations -of server behavior. There are 3 main section in the settings. +of server behavior. There are 3 main sections in the settings. General ~~~~~~~ -`Use repository extra fields` option allows to set a custom fields for each -repository in the system. Each new field consists of 3 attributes `field key`, -`field label`, `field description`. Example usage of such fields would be to -define company specific information into repositories eg. defining repo_manager -key that would add give info about a manager of each repository. There's no -limit for adding custom fields. Newly created fields are accessible via API. +The `Use repository extra fields` option allows to set a custom fields +for each repository in the system. Each new field consists of 3 +attributes: ``field key``, ``field label``, ``field +description``. Example usage of such fields would be to define company +specific information into repositories, e.g., defining a +``repo_manager`` key that would give info about a manager of each +repository. There's no limit for adding custom fields. Newly created +fields are accessible via API. -`Show Kallithea version` option toggles displaying exact Kallithea version in -the footer +The `Show Kallithea version` option toggles displaying the exact +Kallithea version in the footer Dashboard items ~~~~~~~~~~~~~~~ -Number if items in main page dashboard before pagination is displayed +Number of items in main page dashboard before pagination is displayed. Icons
--- a/docs/usage/git_support.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/usage/git_support.rst Tue Mar 31 22:15:38 2015 +0200 @@ -5,16 +5,17 @@ =========== -Kallithea Git support is enabled by default. You just need a git +Kallithea Git support is enabled by default. You just need a Git command line client installed on the server to make Git work fully. Web server with chunked encoding -------------------------------- -Large Git pushes do however require a 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 waitress_ for `paster serve` instead of the built-in `paste` WSGI server. +Large Git pushes requires a 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 +waitress_ for `paster serve` instead of the built-in `paste` WSGI +server. The default paste server is controlled in the .ini file:: @@ -35,8 +36,8 @@ Disabling Git ------------- -You can always disable git/hg support by editing a -file **kallithea/__init__.py** and commenting out the backend. +You can always disable Git or Mercurial support by editing the +file ``kallithea/__init__.py`` and commenting out the backend. .. code-block:: python
--- a/docs/usage/locking.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/usage/locking.rst Tue Mar 31 22:15:38 2015 +0200 @@ -9,30 +9,30 @@ every initial clone and every pull gives users (with write permission) the exclusive right to do a push. -Each repo can be manually unlocked by admin from the repo settings menu. +Each repo can be manually unlocked by an admin from the repo settings menu. | Repos with **locking function=disabled** is the default, that's how repos work today. | Repos with **locking function=enabled** behaves like follows: -Repos have a state called `locked` that can be true or false. -The hg/git commands `hg/git clone`, `hg/git pull`, and `hg/git push` +Repos have a state called ``locked`` that can be true or false. +The hg/git commands ``hg/git clone``, ``hg/git pull``, and ``hg/git push`` influence this state: -- The command `hg/git pull <repo>` will lock that repo (locked=true) +- The command ``hg/git pull <repo>`` will lock that repo (``locked=true``) if the user has write/admin permissions on this repo -- The command `hg/git clone <repo>` will lock that repo (locked=true) if the +- The command ``hg/git clone <repo>`` will lock that repo (``locked=true``) if the user has write/admin permissions on this repo -Kallithea will remember the user id who locked the repo so -only this specific user can unlock the repo (locked=false) by calling +Kallithea will remember the user who locked the repo so +only this specific user can unlock the repo (``locked=false``) by calling -- `hg/git push <repo>` +- ``hg/git push <repo>`` Every other command on that repo from this user and -every command from any other user will result in http return code 423 (locked). +every command from any other user will result in an http return code 423 (locked). Additionally, the http error includes the <user> that locked the repo -(e.g. “repository <repo> locked by user <user>”). +(e.g., “repository <repo> locked by user <user>”).
--- a/docs/usage/performance.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/usage/performance.rst Tue Mar 31 22:15:38 2015 +0200 @@ -4,17 +4,17 @@ Optimizing Kallithea Performance ================================ -When serving large amount of big repositories Kallithea can start -performing slower than expected. Because of demanding nature of handling large -amount of data from version control systems here are some tips how to get +When serving a large amount of big repositories, Kallithea can start +performing slower than expected. Because of the demanding nature of handling large +amounts of data from version control systems, here are some tips on how to get the best performance. * Kallithea will perform better on machines with faster disks (SSD/SAN). It's - more important to have faster disk than faster CPU. + more important to have a faster disk than a faster CPU. * Slowness on initial page can be easily fixed by grouping repositories, and/or - increasing cache size (see below), that includes using lightweight dashboard - option and vcs_full_cache setting in .ini file + increasing cache size (see below). This includes using the lightweight dashboard + option and ``vcs_full_cache`` setting in .ini file Follow these few steps to improve performance of Kallithea system. @@ -22,41 +22,42 @@ 1. Increase cache - in the .ini file:: + In the .ini file:: beaker.cache.sql_cache_long.expire=3600 <-- set this to higher number - This option affects the cache expiration time for main page. Having - few hundreds of repositories on main page can sometimes make the system - to behave slow when cache expires for all of them. Increasing `expire` - option to day (86400) or a week (604800) will improve general response - times for the main page. Kallithea has an intelligent cache expiration - system and it will expire cache for repositories that had been changed. + This option affects the cache expiration time for the main + page. Having several hundreds of repositories on main page can + sometimes make the system behave slowly when the cache expires for + all of them. Increasing the ``expire`` option to a day (86400) or a + week (604800) will improve general response times for the main + page. Kallithea has an intelligent cache expiration system and it + will expire the cache for repositories that have been changed. 2. Switch from sqlite to postgres or mysql - sqlite is a good option when having small load on the system. But due to - locking issues with sqlite, it's not recommended to use it for larger - setup. Switching to mysql or postgres will result in a immediate + sqlite is a good option when having a small load on the system. But due to + locking issues with sqlite, it is not recommended to use it for larger + deployments. Switching to mysql or postgres will result in an immediate performance increase. 3. Scale Kallithea horizontally - Scaling horizontally can give huge performance increase when dealing with + Scaling horizontally can give huge performance increases when dealing with large traffic (large amount of users, CI servers etc). Kallithea can be scaled horizontally on one (recommended) or multiple machines. In order to scale horizontally you need to do the following: - - each instance needs it's own .ini file and unique `instance_id` set in them - - each instance `data` storage needs to be configured to be stored on a - shared disk storage, preferably together with repositories. This `data` - dir contains template caches, sessions, whoosh index and it's used for - tasks locking (so it's safe across multiple instances). Set the - `cache_dir`, `index_dir`, `beaker.cache.data_dir`, `beaker.cache.lock_dir` - variables in each .ini file to shared location across Kallithea instances - - if celery is used each instance should run separate celery instance, but - the message broken should be common to all of them (ex one rabbitmq - shared server) - - load balance using round robin or ip hash, recommended is writing LB rules + - Each instance needs its own .ini file and unique ``instance_id`` set. + - Each instance's ``data`` storage needs to be configured to be stored on a + shared disk storage, preferably together with repositories. This ``data`` + dir contains template caches, sessions, whoosh index and is used for + task locking (so it is safe across multiple instances). Set the + ``cache_dir``, ``index_dir``, ``beaker.cache.data_dir``, ``beaker.cache.lock_dir`` + variables in each .ini file to a shared location across Kallithea instances + - If celery is used each instance should run a separate Celery instance, but + the message broker should be common to all of them (e.g., one + shared RabbitMQ server) + - Load balance using round robin or IP hash, recommended is writing LB rules that will separate regular user traffic from automated processes like CI servers or build bots.
--- a/docs/usage/statistics.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/usage/statistics.rst Tue Mar 31 22:15:38 2015 +0200 @@ -17,16 +17,16 @@ - This happens on each single visit to the statistics page until all commits are fetched. Statistics are kept cached until additional commits are added to the repository. In such a case Kallithea will only fetch the new commits when - updating it's cache. + updating its cache. With Celery enabled ------------------- - On the first visit to the summary page Kallithea will create tasks that will - execute on celery workers. This task will gather all of the stats until all + execute on Celery workers. This task will gather all of the stats until all commits are parsed, each task will parse 250 commits, and run the next task to - parse next 250 commits, until all of the commits are parsed. + parse the next 250 commits until all of the commits are parsed. .. note:: At any time you can disable statistics on each repository via the repository
--- a/docs/usage/subrepos.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/usage/subrepos.rst Tue Mar 31 22:15:38 2015 +0200 @@ -23,14 +23,14 @@ hg ci --message "added remote subrepo" -In the file list of a clone of repo1 you will see a connected subrepo at -revision it was during cloning. -Clicking in subrepos link should send you to proper repository in Kallithea. +In the file list of a clone of ``repo1`` you will see a connected +subrepo at the revision it was at during cloning. Clicking in +subrepos link should send you to the proper repository in Kallithea. -Cloning repo1 will also clone attached subrepository. +Cloning ``repo1`` will also clone the attached subrepository. Next we can edit the subrepo data, and push back to Kallithea. This will update -both of repositories. +both of the repositories. See http://mercurial.aragost.com/kick-start/en/subrepositories/ for more information about subrepositories.
--- a/docs/usage/troubleshooting.rst Tue Mar 31 16:25:49 2015 +0000 +++ b/docs/usage/troubleshooting.rst Tue Mar 31 22:15:38 2015 +0200 @@ -6,49 +6,50 @@ =============== :Q: **Missing static files?** -:A: Make sure either to set the `static_files = true` in the .ini file or +:A: Make sure either to set the ``static_files = true`` in the .ini file or double check the root path for your http setup. It should point to for example: - /home/my-virtual-python/lib/python2.7/site-packages/kallithea/public + ``/home/my-virtual-python/lib/python2.7/site-packages/kallithea/public`` | :Q: **Can't install celery/rabbitmq?** -:A: Don't worry Kallithea works without them too. No extra setup is required. - Try out great celery docs for further help. +:A: Don't worry. Kallithea works without them, too. No extra setup is required. + Try out the great Celery docs for further help. | :Q: **Long lasting push timeouts?** -:A: Make sure you set a longer timeouts in your proxy/fcgi settings, timeouts - are caused by https server and not Kallithea. +:A: Make sure you set a longer timeout in your proxy/fcgi settings. Timeouts + are caused by the http server and not Kallithea. | :Q: **Large pushes timeouts?** -:A: Make sure you set a proper max_body_size for the http server. Very often - Apache, Nginx or other http servers kill the connection due to to large +:A: Make sure you set a proper ``max_body_size`` for the http server. Very often + Apache, Nginx, or other http servers kill the connection due to to large body. | :Q: **Apache doesn't pass basicAuth on pull/push?** -:A: Make sure you added `WSGIPassAuthorization true`. +:A: Make sure you added ``WSGIPassAuthorization true``. | :Q: **Git fails on push/pull?** -:A: Make sure you're using an wsgi http server that can handle chunked encoding - such as `waitress` or `gunicorn`. +:A: Make sure you're using a WSGI http server that can handle chunked encoding + such as ``waitress`` or ``gunicorn``. | :Q: **How can I use hooks in Kallithea?** -:A: It's easy if they are python hooks just use advanced link in hooks section - in Admin panel, that works only for Mercurial. If you want to use githooks, - just install proper one in repository eg. create file in - `/gitrepo/hooks/pre-receive`. You can also use Kallithea-extensions to - connect to callback hooks, for both Git and Mercurial. +:A: It's easy if they are Python hooks: just use advanced link in + hooks section in Admin panel, that works only for Mercurial. If + you want to use Git hooks, just install th proper one in the repository, + e.g., create a file `/gitrepo/hooks/pre-receive`. You can also use + Kallithea-extensions to connect to callback hooks, for both Git + and Mercurial. | @@ -64,7 +65,7 @@ :Q: **Requests hanging on Windows** :A: Please try out with disabled Antivirus software, there are some known problems with Eset Anitivirus. Make sure - you have installed latest windows patches (especially KB2789397). + you have installed the latest Windows patches (especially KB2789397). .. _virtualenv: http://pypi.python.org/pypi/virtualenv