kallithea Changeset - 8867673c8192

Changeset - 8867673c8192

Parent rev.

Child rev.

[Not reviewed]

default

0 9 0

Mads Kiilerich - 10 years ago 2015-08-26 17:28:58
madski@unity3d.com

docs: consistent spacing between text

9 files changed with 0 insertions and 43 deletions:

docs/api/api.rst

docs/installation.rst

docs/installation_win.rst

docs/installation_win_old.rst

docs/setup.rst

docs/usage/general.rst

docs/usage/performance.rst

docs/usage/troubleshooting.rst

docs/usage/vcs_support.rst

0 comments (0 inline, 0 general)

docs/api/api.rst

➞

Show inline comments

@@ @@ -231,378 +231,367 @@ INPUT:: @@
 OUTPUT::
     id : <id_given_in_input>
     result : {
                  "ip_addr_server": <ip_from_clien>",
                  "user_ips": [
+                                {
                                    "ip_addr": "<ip_with_mask>",
                                    "ip_range": ["<start_ip>", "<end_ip>"],
                                 },
                                 ...
+                             ]
+             }
     error :  null
 get_user
 --------
 Get a user by username or userid. The result is empty if user can't be found.
 If userid param is skipped, it is set to id of user who is calling this method.
 Any userid can be specified when the command is executed using the api_key of a user with admin rights.
 Regular users can only speicy their own userid.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_user"
     args :    {
                 "userid" : "<username or user_id Optional(=apiuser)>"
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: None if user does not exist or
+            {
                 "user_id" :     "<user_id>",
                 "api_key" :     "<api_key>",
                 "username" :    "<username>",
                 "firstname":    "<firstname>",
                 "lastname" :    "<lastname>",
                 "email" :       "<email>",
                 "emails":       "<list_of_all_additional_emails>",
                 "ip_addresses": "<list_of_ip_addresses_for_user>",
                 "active" :      "<bool>",
                 "admin" :       "<bool>",
                 "ldap_dn" :     "<ldap_dn>",
                 "last_login":   "<last_login>",
                 "permissions": {
                     "global": ["hg.create.repository",
                                "repository.read",
                                "hg.register.manual_activate"],
                     "repositories": {"repo1": "repository.none"},
                     "repositories_groups": {"Group1": "group.read"}
                  },
+            }
     error:  null
 get_users
 ---------
 List all existing users.
 This command can only be executed using the api_key of a user with admin rights.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_users"
     args :    { }
 OUTPUT::
     id : <id_given_in_input>
     result: [
+              {
                 "user_id" :     "<user_id>",
                 "api_key" :     "<api_key>",
                 "username" :    "<username>",
                 "firstname":    "<firstname>",
                 "lastname" :    "<lastname>",
                 "email" :       "<email>",
                 "emails":       "<list_of_all_additional_emails>",
                 "ip_addresses": "<list_of_ip_addresses_for_user>",
                 "active" :      "<bool>",
                 "admin" :       "<bool>",
                 "ldap_dn" :     "<ldap_dn>",
                 "last_login":   "<last_login>",
               },
               …
+            ]
     error:  null
 .. _create-user:
 create_user
 -----------
 Create new user.
 This command can only be executed using the api_key of a user with admin rights.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "create_user"
     args :    {
                 "username" :  "<username>",
                 "email" :     "<useremail>",
                 "password" :  "<password = Optional(None)>",
                 "firstname" : "<firstname> = Optional(None)",
                 "lastname" :  "<lastname> = Optional(None)",
                 "active" :    "<bool> = Optional(True)",
                 "admin" :     "<bool> = Optional(False)",
                 "ldap_dn" :   "<ldap_dn> = Optional(None)"
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: {
               "msg" : "created new user `<username>`",
               "user": {
                 "user_id" :  "<user_id>",
                 "username" : "<username>",
                 "firstname": "<firstname>",
                 "lastname" : "<lastname>",
                 "email" :    "<email>",
                 "emails":    "<list_of_all_additional_emails>",
                 "active" :   "<bool>",
                 "admin" :    "<bool>",
                 "ldap_dn" :  "<ldap_dn>",
                 "last_login": "<last_login>",
               },
+            }
     error:  null
 Example::
     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
 -----------
 Update the given user if such user exists.
 This command can only be executed using the api_key of a user with admin rights.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "update_user"
     args :    {
                 "userid" : "<user_id or username>",
                 "username" :  "<username> = Optional(None)",
                 "email" :     "<useremail> = Optional(None)",
                 "password" :  "<password> = Optional(None)",
                 "firstname" : "<firstname> = Optional(None)",
                 "lastname" :  "<lastname> = Optional(None)",
                 "active" :    "<bool> = Optional(None)",
                 "admin" :     "<bool> = Optional(None)",
                 "ldap_dn" :   "<ldap_dn> = Optional(None)"
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: {
               "msg" : "updated user ID:<userid> <username>",
               "user": {
                 "user_id" :  "<user_id>",
                 "api_key" :  "<api_key>",
                 "username" : "<username>",
                 "firstname": "<firstname>",
                 "lastname" : "<lastname>",
                 "email" :    "<email>",
                 "emails":    "<list_of_all_additional_emails>",
                 "active" :   "<bool>",
                 "admin" :    "<bool>",
                 "ldap_dn" :  "<ldap_dn>",
                 "last_login": "<last_login>",
               },
+            }
     error:  null
 delete_user
 -----------
 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.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "delete_user"
     args :    {
                 "userid" : "<user_id or username>",
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: {
               "msg" : "deleted user ID:<userid> <username>",
               "user": null
+            }
     error:  null
 get_user_group
 --------------
 Get an existing user group.
 This command can only be executed using the api_key of a user with admin rights.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_user_group"
     args :    {
                 "usergroupid" : "<user group id or name>"
+              }
 OUTPUT::
     id : <id_given_in_input>
     result : None if group not exist
+             {
                "users_group_id" : "<id>",
                "group_name" :     "<groupname>",
                "active":          "<bool>",
                "members" :  [
+                              {
                                 "user_id" :  "<user_id>",
                                 "api_key" :  "<api_key>",
                                 "username" : "<username>",
                                 "firstname": "<firstname>",
                                 "lastname" : "<lastname>",
                                 "email" :    "<email>",
                                 "emails":    "<list_of_all_additional_emails>",
                                 "active" :   "<bool>",
                                 "admin" :    "<bool>",
                                 "ldap_dn" :  "<ldap_dn>",
                                 "last_login": "<last_login>",
                               },
                               …
+                            ]
+             }
     error : null
 get_user_groups
 ---------------
 List all existing user groups.
 This command can only be executed using the api_key of a user with admin rights.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_user_groups"
     args :    { }
 OUTPUT::
     id : <id_given_in_input>
     result : [
+               {
                "users_group_id" : "<id>",
                "group_name" :     "<groupname>",
                "active":          "<bool>",
                },
                …
+              ]
     error : null
 create_user_group
 -----------------
 Create a new user group.
 This command can only be executed using the api_key of a user with admin rights.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "create_user_group"
     args:     {
                 "group_name": "<groupname>",
                 "owner" :     "<owner_name_or_id = Optional(=apiuser)>",
                 "active":     "<bool> = Optional(True)"
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: {
               "msg": "created new user group `<groupname>`",
               "users_group": {
                      "users_group_id" : "<id>",
                      "group_name" :     "<groupname>",
                      "active":          "<bool>",
                },
+            }
     error:  null
 add_user_to_user_group
 ----------------------
 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.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "add_user_user_group"
     args:     {
                 "usersgroupid" : "<user group id or name>",
                 "userid" : "<user_id or username>",
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: {
               "success": True|False # depends on if member is in group
               "msg": "added member `<username>` to a user group `<groupname>` |
                       User is already in that group"
+            }
     error:  null
 remove_user_from_user_group
 ---------------------------
 Remove a user from a user group. If the user isn't in the given group, success will
 be ``false``.
 This command can only be executed using the api_key of a user with admin rights.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "remove_user_from_user_group"
     args:     {
                 "usersgroupid" : "<user group id or name>",
                 "userid" : "<user_id or username>",
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: {
               "success":  True|False,  # depends on if member is in group
               "msg": "removed member <username> from user group <groupname> |
                       User wasn't in group"
+            }
     error:  null
 get_repo
 --------
 Get an existing repository by its name or repository_id. Members will contain
@@ @@ -677,123 +666,120 @@ OUTPUT:: @@
                                     "username" :    "<username>",
                                     "api_key" :     "<api_key>",
                                     "firstname":    "<firstname>",
                                     "lastname" :    "<lastname>",
                                     "email" :       "<email>",
                                     "emails":       "<list_of_all_additional_emails>",
                                     "ip_addresses": "<list_of_ip_addresses_for_user>",
                                     "active" :      "<bool>",
                                     "admin" :       "<bool>",
                                     "ldap_dn" :     "<ldap_dn>",
                                     "last_login":   "<last_login>",
                                   },
                                   …
+                 ]
+            }
     error:  null
 get_repos
 ---------
 List all existing repositories.
 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.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_repos"
     args:     { }
 OUTPUT::
     id : <id_given_in_input>
     result: [
+              {
                 "repo_id" :          "<repo_id>",
                 "repo_name" :        "<reponame>"
                 "repo_type" :        "<repo_type>",
                 "clone_uri" :        "<clone_uri>",
                 "private" :          "<bool>",
                 "created_on" :       "<datetimecreated>",
                 "description" :      "<description>",
                 "landing_rev":       "<landing_rev>",
                 "owner":             "<repo_owner>",
                 "fork_of":           "<name_of_fork_parent>",
                 "enable_downloads":  "<bool>",
                 "enable_locking":    "<bool>",
                 "enable_statistics": "<bool>",
               },
               …
+            ]
     error:  null
 get_repo_nodes
 --------------
 Return a list of files and directories for a given path at the given revision.
 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.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "get_repo_nodes"
     args:     {
                 "repoid" : "<reponame or repo_id>"
                 "revision"  : "<revision>",
                 "root_path" : "<root_path>",
                 "ret_type"  : "<ret_type> = Optional('all')"
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: [
+              {
                 "name" :        "<name>"
                 "type" :        "<type>",
               },
               …
+            ]
     error:  null
 create_repo
 -----------
 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.
 This command can only be executed using the api_key of a user with admin rights,
 or that of a regular user with create repository permission.
 Regular users cannot specify owner parameter.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "create_repo"
     args:     {
                 "repo_name" :        "<reponame>",
                 "owner" :            "<owner_name_or_id = Optional(=apiuser)>",
                 "repo_type" :        "<repo_type> = Optional('hg')",
                 "description" :      "<description> = Optional('')",
                 "private" :          "<bool> = Optional(False)",
                 "clone_uri" :        "<clone_uri> = Optional(None)",
                 "landing_rev" :      "<landing_rev> = Optional('tip')",
                 "enable_downloads":  "<bool> = Optional(False)",
                 "enable_locking":    "<bool> = Optional(False)",
                 "enable_statistics": "<bool> = Optional(False)",
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: {
               "msg": "Created new repository `<reponame>`",
               "repo": {
@@ @@ -801,49 +787,48 @@ OUTPUT:: @@
                 "repo_name" :        "<reponame>"
                 "repo_type" :        "<repo_type>",
                 "clone_uri" :        "<clone_uri>",
                 "private" :          "<bool>",
                 "created_on" :       "<datetimecreated>",
                 "description" :      "<description>",
                 "landing_rev":       "<landing_rev>",
                 "owner":             "<username or user_id>",
                 "fork_of":           "<name_of_fork_parent>",
                 "enable_downloads":  "<bool>",
                 "enable_locking":    "<bool>",
                 "enable_statistics": "<bool>",
               },
+            }
     error:  null
 update_repo
 -----------
 Update 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 create repository permission.
 Regular users cannot specify owner parameter.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "update_repo"
     args:     {
                 "repoid" :           "<reponame or repo_id>"
                 "name" :             "<reponame> = Optional('')",
                 "group" :            "<group_id> = Optional(None)",
                 "owner" :            "<owner_name_or_id = Optional(=apiuser)>",
                 "description" :      "<description> = Optional('')",
                 "private" :          "<bool> = Optional(False)",
                 "clone_uri" :        "<clone_uri> = Optional(None)",
                 "landing_rev" :      "<landing_rev> = Optional('tip')",
                 "enable_downloads":  "<bool> = Optional(False)",
                 "enable_locking":    "<bool> = Optional(False)",
                 "enable_statistics": "<bool> = Optional(False)",
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: {
               "msg": "updated repo ID:repo_id `<reponame>`",
@@ @@ -865,163 +850,158 @@ OUTPUT:: @@
                                        "author":   "<full_author>",
                                        "date":     "<date_time_of_commit>",
                                        "message":  "<commit_message>",
                                        "raw_id":   "<raw_id>",
                                        "revision": "<numeric_revision>",
                                        "short_id": "<short_id>"
+                                     }
                 "locked_by": "<username>",
                 "locked_date": "<float lock_time>",
               },
+            }
     error:  null
 fork_repo
 ---------
 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 with the global fork permission, by a regular user with create
 repository permission and at least read access to the repository.
 Regular users cannot specify owner parameter.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "fork_repo"
     args:     {
                 "repoid" :          "<reponame or repo_id>",
                 "fork_name":        "<forkname>",
                 "owner":            "<username or user_id = Optional(=apiuser)>",
                 "description":      "<description>",
                 "copy_permissions": "<bool>",
                 "private":          "<bool>",
                 "landing_rev":      "<landing_rev>"
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: {
               "msg": "Created fork of `<reponame>` as `<forkname>`",
               "success": true
+            }
     error:  null
 delete_repo
 -----------
 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 is possible to detach or delete forks of the deleted repository.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "delete_repo"
     args:     {
                 "repoid" : "<reponame or repo_id>",
                 "forks"  : "`delete` or `detach` = Optional(None)"
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: {
               "msg": "Deleted repository `<reponame>`",
               "success": true
+            }
     error:  null
 grant_user_permission
 ---------------------
 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.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "grant_user_permission"
     args:     {
                 "repoid" : "<reponame or repo_id>"
                 "userid" : "<username or user_id>"
                 "perm" :       "(repository.(none|read|write|admin))",
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: {
               "msg" : "Granted perm: `<perm>` for user: `<username>` in repo: `<reponame>`",
               "success": true
+            }
     error:  null
 revoke_user_permission
 ----------------------
 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.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method  : "revoke_user_permission"
     args:     {
                 "repoid" : "<reponame or repo_id>"
                 "userid" : "<username or user_id>"
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: {
               "msg" : "Revoked perm for user: `<username>` in repo: `<reponame>`",
               "success": true
+            }
     error:  null
 grant_user_group_permission
 ---------------------------
 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.
 INPUT::
     id : <id_for_response>
     api_key : "<api_key>"
     method :  "grant_user_group_permission"
     args:     {
                 "repoid" : "<reponame or repo_id>"
                 "usersgroupid" : "<user group id or name>"
                 "perm" : "(repository.(none|read|write|admin))",
+              }
 OUTPUT::
     id : <id_given_in_input>
     result: {
               "msg" : "Granted perm: `<perm>` for group: `<usersgroupname>` in repo: `<reponame>`",
               "success": true
+            }
     error:  null
 revoke_user_group_permission
 ----------------------------
 Revoke permission for a user group on the given repository.

docs/installation.rst

➞

Show inline comments

@@ @@ -102,104 +102,96 @@ For installation without virtualenv, 'ju @@
     pip install kallithea
 Note that this method requires root privileges and will install packages
 globally without using the system's package manager.
 To install as a regular user in ``~/.local``, you can use::
     pip install --user kallithea
 You can now proceed to :ref:`setup`.
 Upgrading Kallithea from Python Package Index (PyPI)
 ----------------------------------------------------
 .. note::
    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
    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``.
 If using a SQLite database, stop the Kallithea process/daemon/service, and
 then make a copy of the database file::
  service kallithea stop
  cp kallithea.db kallithea.db.{version}
 Back up your configuration file::
  cp my.ini my.ini.{version}
 Ensure that you are using the Python virtual environment that you originally
 installed Kallithea in by running::
  pip freeze
 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
 Once you have verified the environment you can upgrade Kallithea with::
  pip install --upgrade kallithea
 Then run the following command from the installation directory::
  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 is recommended
 that you recheck the content after the automerge.
 .. note::
    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
 the new whoosh version could introduce some incompatible index changes. Please
 read the changelog to see if there were any changes to whoosh.
 The final step is to upgrade the database. To do this simply run::
  paster upgrade-db my.ini
 This will upgrade the schema and update some of the defaults in the database,
 and will always recheck the settings of the application, if there are no new
 options that need to be set.
 .. note::
    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`
 You may find it helpful to clear out your log file so that new errors are
 readily apparent::
  echo > kallithea.log
 Once that is complete, you may now start your upgraded Kallithea Instance::
  service kallithea start
 Or::
  paster serve /srv/kallithea/my.ini
 .. note::
    If you're using Celery, make sure you restart all instances of it after
    upgrade.

docs/installation_win.rst

➞

Show inline comments

@@ @@ -185,49 +185,48 @@ The script will ask you for confirmation @@
 The script will ask you for the repository path, answer C:\\Kallithea\\Repos (or similar).
 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).
 If you make a mistake and the script doesn't end, don't worry: start it again.
 If you decided not to install git, you will get errors about it that you can ignore.
 Step 10 - Running Kallithea
 ---------------------------
 In the previous command prompt, being in the C:\\Kallithea\\Bin folder, type::
   paster serve production.ini
 Open your web server, and go to http://127.0.0.1:5000
 It works!! :-)
 Remark:
 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:
 - Installing Celery
 - Running Kallithea as a Windows Service. You can investigate here:
   - http://pypi.python.org/pypi/wsgisvc
   - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/
   - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service
 - Using Apache. You can investigate here:
   - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4
 Upgrading
 :::::::::
 Stop running Kallithea
 Open a CommandPrompt like in Step 7 (cd to C:\Kallithea\Env\Scripts and activate) and type::
   pip install kallithea --upgrade
   cd \Kallithea\Bin
 Backup your production.ini file now.

docs/installation_win_old.rst

➞

Show inline comments

@@ @@ -157,49 +157,48 @@ to include it) @@
 Step 7 -- Install Kallithea
 ---------------------------
 Finally, install Kallithea
 Close previously opened command prompt/s, and open a Visual Studio 2008
 Command Prompt (**IMPORTANT!!**). To do so, go to Start Menu, and then open
 "Microsoft Visual C++ 2008 Express Edition" -> "Visual Studio Tools" ->
 "Visual Studio 2008 Command Prompt"
 .. note::
 -bit: For 64-bit you need to modify the shortcut that is used to start the
    Visual Studio 2008 Command Prompt. Use right-mouse click to open properties.
 Change commandline from::
 %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" x86
 to::
 %comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" amd64
 In that CMD (loaded with VS2008 PATHs) type::
   cd C:\Kallithea\Env\Scripts (or similar)
   activate
 The prompt will change into "(Env) C:\\Kallithea\\Env\\Scripts" or similar
 (depending of your folder structure). Then type::
  pip install kallithea
 (long step, please wait until fully complete)
 Some warnings will appear, don't worry as they are normal.
 Step 8 -- Configuring Kallithea
 -------------------------------
 steps taken from http://packages.python.org/Kallithea/setup.html
 You have to use the same Visual Studio 2008 command prompt as Step7, so
 if you closed it reopen it following the same commands (including the
 "activate" one). When ready, just type::
   cd C:\Kallithea\Bin
@@ @@ -226,49 +225,48 @@ The script will ask you for repository p @@
 The script will ask you for 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)
 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::
  paster serve production.ini
 Open yout web server, and go to http://127.0.0.1:5000
 It works!! :-)
 Remark:
 If it does not work first time, just Ctrl-C the CMD process and start it
 again. Don't forget the "http://" in Internet Explorer
 What this Guide does not cover:
 - Installing Celery
 - Running Kallithea as Windows Service. You can investigate here:
   - http://pypi.python.org/pypi/wsgisvc
   - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/
   - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service
 - Using Apache. You can investigate here:
   - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4
 Upgrading
 :::::::::
 Stop running Kallithea
 Open a CommandPrompt like in Step7 (VS2008 path + activate) and type::
  easy_install -U kallithea
  cd \Kallithea\Bin
 { backup your production.ini file now} ::

docs/setup.rst

➞

Show inline comments

 .. _setup:
 =====
 Setup
 =====
 Setting up Kallithea
 --------------------
 First, you will need to create a Kallithea configuration file. Run the
 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.
 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``
 configuration file to use this other database. Kallithea currently supports
 PostgreSQL, SQLite and MySQL databases. Create the database by running
 the following command::
     paster setup-db my.ini
 This will prompt you for a "root" path. This "root" path is the location where
 Kallithea will store all of its repositories on the current machine. After
 entering this "root" path ``setup-db`` will also prompt you for a username
 and password for the initial admin account which ``setup-db`` sets
 up for you.
 The ``setup-db`` values can also be given on the command line.
 Example::
     paster setup-db my.ini --user=nn --password=secret --email=nn@example.org --repos=/srv/repos
 The ``setup-db`` command will create all 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 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
   http://127.0.0.1:5000. The IP address and port is configurable via the
   configuration file created in the previous step.
 - Log in to Kallithea using the admin account created when running ``setup-db``.
 - The default permissions on each repository is read, and the owner is admin.
   Remember to update these if needed.
@@ @@ -123,49 +121,48 @@ authentication is fully supported. @@
 Setting up Whoosh full text search
 ----------------------------------
 Kallithea provides full text search of repositories using `Whoosh`__.
 .. __: https://pythonhosted.org/Whoosh/
 For an incremental index build, run::
     paster make-index my.ini
 For a full index rebuild, run::
     paster make-index my.ini -f
 The ``--repo-location`` option allows the location of the repositories to be overriden;
 usually, the location is retrieved from the Kallithea database.
 The ``--index-only`` option can be used to limit the indexed repositories to a comma-separated list::
     paster make-index my.ini --index-only=vcs,kallithea
 To keep your index up-to-date it is necessary to do periodic index builds;
 for this, it is recommended to use a crontab entry. Example::
 3  *  *  *  /path/to/virtualenv/bin/paster make-index /path/to/kallithea/my.ini
 When using incremental mode (the default), Whoosh will check the last
 modification date of each file and add it to be reindexed if a newer file is
 available. The indexing daemon checks for any removed files and removes them
 from index.
 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" checkbox.
 Setting up LDAP support
 -----------------------
 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::
     pip install python-ldap
 .. note:: ``python-ldap`` requires some libraries to be installed on
@@ @@ -409,49 +406,48 @@ configure the authentication and add the @@
 For example, the following config section for Apache sets a subdirectory in a
 reverse-proxy setup with basic auth:
 .. code-block:: apache
     <Location /someprefix>
       ProxyPass http://127.0.0.1:5000/someprefix
       ProxyPassReverse http://127.0.0.1:5000/someprefix
       SetEnvIf X-Url-Scheme https HTTPS=1
       AuthType Basic
       AuthName "Kallithea authentication"
       AuthUserFile /srv/kallithea/.htpasswd
       Require valid-user
       RequestHeader unset X-Forwarded-User
       RewriteEngine On
       RewriteCond %{LA-U:REMOTE_USER} (.+)
       RewriteRule .* - [E=RU:%1]
       RequestHeader set X-Forwarded-User %{RU}e
     </Location>
 .. note::
    If you enable proxy pass-through authentication, make sure your server is
    only accessible through the proxy. Otherwise, any client would be able to
    forge the authentication header and could effectively become authenticated
    using any account of their liking.
 Integration with issue trackers
 -------------------------------
 Kallithea provides a simple integration with issue trackers. It's possible
 to define a regular expression that will match an issue ID in commit messages,
 and have that replaced 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
 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``.
@@ @@ -515,49 +511,48 @@ cloning repositories or sending emails. @@
 Kallithea will in most setups work perfectly fine out of the box (without
 Celery), executing all tasks in the web server process. Some tasks can however
 take some time to run and it can be better to run such tasks asynchronously in
 a separate process so the web server can focus on serving web requests.
 For installation and configuration of Celery, see the `Celery documentation`_.
 Note that Celery requires a message broker service like RabbitMQ_ (recommended)
 or Redis_.
 The use of Celery is configured in the Kallithea ini configuration file.
 To enable it, simply set::
   use_celery = true
 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
 `broker.host` in the configuration file.
 To start the Celery process, run::
  paster celeryd <configfile.ini>
 .. note::
    Make sure you run this command from the same virtualenv, and with the same
    user that Kallithea runs.
 HTTPS support
 -------------
 Kallithea will by default generate URLs based on the WSGI environment.
 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
   ``X-Url-Scheme``, ``X-Forwarded-Scheme`` or ``X-Forwarded-Proto`` HTTP header
   (default ``http``).
 - With ``force_https = true`` the default will be ``https``.
 - With ``use_htsts = true``, Kallithea will set ``Strict-Transport-Security`` when using https.
 Nginx virtual host example
 --------------------------
 Sample config for Nginx using proxy:
@@ @@ -656,49 +651,48 @@ Here is a sample configuration file for @@
             ServerName hg.myserver.com
             ServerAlias hg.myserver.com
             <Proxy *>
               # For Apache 2.4 and later:
               Require all granted
               # For Apache 2.2 and earlier, instead use:
               # Order allow,deny
               # Allow from all
             </Proxy>
             #important !
             #Directive to properly generate url (clone url) for pylons
             ProxyPreserveHost On
             #kallithea instance
             ProxyPass / http://127.0.0.1:5000/
             ProxyPassReverse / http://127.0.0.1:5000/
             #to enable https use line below
             #SetEnvIf X-Url-Scheme https HTTPS=1
     </VirtualHost>
 Additional tutorial
 http://pylonsbook.com/en/1.1/deployment.html#using-apache-to-proxy-requests-to-pylons
 Apache as subdirectory
 ----------------------
 Apache subdirectory part:
 .. code-block:: apache
     <Location /<someprefix> >
       ProxyPass http://127.0.0.1:5000/<someprefix>
       ProxyPassReverse http://127.0.0.1:5000/<someprefix>
       SetEnvIf X-Url-Scheme https HTTPS=1
     </Location>
 Besides the regular apache setup you will need to add the following line
 into ``[app:main]`` section of your .ini file::
     filter-with = proxy-prefix
 Add the following at the end of the .ini file::
@@ @@ -713,49 +707,48 @@ then change ``<someprefix>`` into your c @@
 Apache with mod_wsgi
 --------------------
 Alternatively, Kallithea can be set up with Apache under mod_wsgi. For
 that, you'll need to:
 - Install mod_wsgi. If using a Debian-based distro, you can install
   the package libapache2-mod-wsgi::
     aptitude install libapache2-mod-wsgi
 - Enable mod_wsgi::
     a2enmod wsgi
 - Create a wsgi dispatch script, like the one below. Make sure you
   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,
   as in the following example. Once again, check the paths are
   correctly specified.
 Here is a sample excerpt from an Apache Virtual Host configuration file:
 .. code-block:: apache
     WSGIDaemonProcess kallithea \
         processes=1 threads=4 \
         python-path=/srv/kallithea/pyenv/lib/python2.7/site-packages
     WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
     WSGIPassAuthorization On
 Or if using a dispatcher WSGI script with proper virtualenv activation:
 .. code-block:: apache
     WSGIDaemonProcess kallithea processes=1 threads=4
     WSGIScriptAlias / /srv/kallithea/dispatch.wsgi
     WSGIPassAuthorization On
 .. 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.
 .. note::
    If running Kallithea in multiprocess mode,
    make sure you set ``instance_id = *`` in the configuration so each process

docs/usage/general.rst

➞

Show inline comments

@@ @@ -111,49 +111,48 @@ Emails are also sent for comments on cha @@
 to the committer of the changeset (if known to Kallithea), to all reviewers of
 the pull request (if applicable) and to all people mentioned in the comment
 using @mention notation.
 Trending source files
 ---------------------
 Trending source files are calculated based on a predefined dictionary of known
 types and extensions. If an extension is missing or you would like to scan
 custom files, it is possible to extend the ``LANGUAGES_EXTENSIONS_MAP``
 dictionary located in ``kallithea/config/conf.py`` with new types.
 Cloning remote repositories
 ---------------------------
 Kallithea has the ability to clone repositories from given remote locations.
 Currently it supports the following options:
 - hg  -> hg clone
 - svn -> hg clone
 - git -> git clone
 .. note:: svn -> hg cloning requires the ``hgsubversion`` library to be
    installed.
 If you need to clone repositories that are protected via basic authentication,
 you can pass the credentials in the URL, e.g.
 ``http://user:passw@remote.server/repo``. Kallithea will then try to login and
 clone using the given credentials. Please note that the given credentials will
 be stored as plaintext inside the database. However, the authentication
 information will not be shown in the clone URL on the summary page.
 Specific features configurable in the Admin settings
 ----------------------------------------------------
 In general, the Admin settings should be self-explanatory and will not be
 described in more detail in this documentation. However, there are a few
 features that merit further explanation.
 Repository extra fields
 ~~~~~~~~~~~~~~~~~~~~~~~
 In the *Visual* tab, there is an option "Use repository extra
 fields", which allows to set custom fields for each repository in the system.

docs/usage/performance.rst

➞

Show inline comments

 .. _performance:
 ================================
 Optimizing Kallithea performance
 ================================
 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 is often I/O bound, and hence a fast disk (SSD/SAN) is
   usually more important than a fast CPU.
 * Sluggish loading of the front page can easily be fixed by grouping repositories or by
   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.
 . Increase cache
     Tweak beaker cache settings in the ini file. The actual effect of that
     is questionable.
 . Switch from SQLite to PostgreSQL or MySQL
     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 PostgreSQL will result in an immediate
     performance increase. A tool like SQLAlchemyGrate_ can be used for
     migrating to another database platform.
 . Scale Kallithea horizontally
     Scaling horizontally can give huge performance benefits when dealing with
     large amounts of traffic (many 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 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

docs/usage/troubleshooting.rst

➞

Show inline comments

 .. _troubleshooting:
 ===============
 Troubleshooting
 ===============
 :Q: **Missing static files?**
 :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``
+|
 :Q: **Can't install celery/rabbitmq?**
 :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 timeout in your proxy/fcgi settings. Timeouts
     are caused by the http server and not Kallithea.
+|

docs/usage/vcs_support.rst

➞

Show inline comments

@@ @@ -18,49 +18,48 @@ file ``kallithea/__init__.py`` and comme @@
+   }
 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
 waitress_ for `paster serve` instead of the built-in `paste` WSGI
 server.
 The paster server is controlled in the .ini file::
     use = egg:waitress#main
 or::
     use = egg:gunicorn#main
 Also make sure to comment out the following options::
     threadpool_workers =
     threadpool_max_requests =
     use_threadpool =
 Mercurial support
 -----------------
 Working with Mercurial subrepositories
 ``````````````````````````````````````
 This section explains how to use Mercurial subrepositories_ in Kallithea.
 Example usage::
     ## init a simple repo
     hg init mainrepo
     cd mainrepo
     echo "file" > file
     hg add file
     hg ci --message "initial file"

0 comments (0 inline, 0 general)