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

Stable releases of RhodeCode are best installed via::

Or::

Detailed instructions and links may be found on the Installation page.

more details

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

Online documentation for the current version of RhodeCode is available at

You may also build the documentation for yourself - go into ``docs/`` and run::

	@echo

	@echo "Build finished; now you can run "qcollectiongenerator" with the" \

	      ".qhcp project file in $(BUILDDIR)/qthelp, like this:"

	@echo "To view the help file:"

devhelp:

	$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp

	@echo

	@echo "Build finished."

	@echo "To view the help file:"

	@echo "# devhelp"

epub:

===

There's a single schema for calling all api methods. API is implemented

<your_server>/_admin/api

API ACCESS FOR WEB VIEWS

++++++++++++++++++++++++

decorated with `@LoginRequired` decorator. To enable API access simple change

the standard login decorator to `@LoginRequired(api_access=True)`.

of views that will have API access enabled. Simply edit `api_access_controllers_whitelist`

option in your .ini file, and define views that should have API access enabled.

Following example shows how to enable API access to patch/diff raw file and archive

    api_access_controllers_whitelist =

        ChangesetController:changeset_patch,

        FilesController:archivefile

GET parameter `?api_key=<api_key>` to url. By default this is only

enabled on RSS/ATOM feed views. Exposing raw diffs is a good way to integrate with

3rd party services like code review, or build farms that could download archives.

    api_key can be found in your user account page

    {

        "id":<id>, # matching id sent by request

API CLIENT

++++++++++

will be available.

To get started quickly simply run::

 kallithea-api get_repo

 calling {"api_key": "<apikey>", "id": 75, "args": {}, "method": "get_repo"} to http://127.0.0.1:5000

 {'error': 'Missing non optional `repoid` arg in JSON DATA',

  'id': 75,

  'result': None}

Let's try again now giving the repoid as parameters::

    {'error': None,

     'id': 39,

     'result': <json data...>}

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

Dispatch rescan repositories action. If remove_obsolete is set

This command can be executed only using api_key belonging to user with admin

rights.

show_ip

-------

defined IP addresses for given user.

This command can be executed only using api_key belonging to user with admin

rights.

# -*- coding: utf-8 -*-

#

# sphinx-quickstart on Sun Oct 10 16:46:37 2010.

#

# This file is execfile()d with the current directory set to its containing dir.

master_doc = 'index'

# General information about the project.

copyright = u'%s, Marcin Kuzminski' % (datetime.datetime.now().year)

# The version info for the project you're documenting, acts as replacement for

#html_file_suffix = None

# Output file base name for HTML help builder.

# -- Options for LaTeX output --------------------------------------------------

# Grouping the document tree into LaTeX files. List of tuples

# (source start file, target name, title, author, documentclass [howto/manual]).

latex_documents = [

   u'Marcin Kuzminski', 'manual'),

]

# One entry per manual page. List of tuples

# (source start file, name, description, authors, manual section).

man_pages = [

     [u'Marcin Kuzminski'], 1)

]

.. _contributing:

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

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

greatly appreciated!

Could I request that you make your source contributions by first forking the

https://bitbucket.org/conservancy/kallithea and then make your changes to

your forked repository. Please post all fixes into **dev** bookmark since your

change might be already fixed there and i try to merge all fixes from dev into

stable, and not the other way. Finally, when you are finished with your changes,

    hg clone https://kallithea-scm.org/repos/kallithea

    python setup.py develop

| Thank you for any contributions!

.. _bitbucket: http://bitbucket.org/

Installation

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

sure, your not missing any system libraries and using right version of

**1.6**. If you're using older client, please upgrade.

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

Or::

    python setup.py install

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

python and making things less problematic when doing system python updates.

Alternative very detailed installation instructions for Ubuntu Server with

- Assuming you have installed virtualenv_ create a new virtual environment

  using virtualenv command::

.. note:: Using ``--no-site-packages`` when generating your

   virtualenv is **very important**. This flag provides the necessary

   isolation for running the set of packages required by

   the virtualenv, or, even if it does, may not run properly,

   depending on the packages you've already got installed into your

   Python's "main" site-packages dir.

- Activate the virtualenv_ by running::

.. note:: If you're using UNIX, *do not* use ``sudo`` to run the

   ``virtualenv`` script.  It's perfectly acceptable (and desirable)

   to create a virtualenv as a normal user.

  filesystem. For example::

  or::

  python libraries into activated virtualenv

Requirements for Celery (optional)

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

In order to gain maximum performance

together with celery you have to install some kind of message broker,

recommended one is rabbitmq_ to make the async tasks work.

any third party applications. However, using Celery_ will give you a large

speed improvement when using many big repositories. If you plan to use

without celery running.

celeryd using paster and message broker together with the application.

.. note::

   work perfectly fine without them.

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

Target OS: Windows XP SP3 32bit English (Clean installation)

+ All Windows Updates until 24-may-2012

  Typically: C:\\Python27

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

it. However, this guide will follow the proposed structure, so please

later adapt the paths if you change them. My recommendation is to use

folders with NO SPACES. But you can try if you are brave...

Create the following folder structure::

Step6 - Install virtualenv

Navigate to: http://www.virtualenv.org/en/latest/index.html#installation

Right click on "virtualenv.py" file and choose "Save link as...".

(the file is located at

https://raw.github.com/pypa/virtualenv/master/virtualenv.py)

do so, open a CMD (Python Path should be included in Step3), navigate

where you downloaded "virtualenv.py", and write::

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

to include it)

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

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

In that CMD (loaded with VS2008 PATHs) type::

  activate

(depending of your folder structure). Then type::

(long step, please wait until fully complete)

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

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

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::

Then, you must edit production.ini to fit your needs (ip address, ip

port, mail settings, database, whatever). I recommend using NotePad++

 paster setup-db production.ini

(this time a NEW database will be installed, you must follow a different

The script will ask you for confirmation about creating a NEW database,

answer yes (y)

(or similar)

The script will ask you for admin username and password, answer "admin"

+ "123456" (or whatever you want)

it again.

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

just type::

 paster serve production.ini

What this Guide does not cover:

- Installing Celery

  - http://pypi.python.org/pypi/wsgisvc

  - http://ryrobes.com/python/running-python-scripts-as-a-windows-service/

Upgrading

=========

Open a CommandPrompt like in Step7 (VS2008 path + activate) and type::

{ backup your production.ini file now} ::

(check changes and update your production.ini accordingly) ::

 paster upgrade-db production.ini (update database)

	echo.

	echo.Build finished; now you can run "qcollectiongenerator" with the ^

.qhcp project file in %BUILDDIR%/qthelp, like this:

	echo.To view the help file:

	goto end

)

=====

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

following command to do this::

- This will create the file `production.ini` in the current directory. This

  port, email settings, usage of static files, cache, celery settings and

  logging.

use postgresql or sqlite (default). If you choose a database other than the

default ensure you properly adjust the db url in your production.ini

postgresql, sqlite and mysql databases. Create the database by running

the following command::

    paster setup-db production.ini

This will prompt you for a "root" path. This "root" path is the location where

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`` 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

  add all of the repositories at the chosen location to it's database.

  (Note: make sure you specify the correct path to the root).

- Note: the given path for mercurial_ repositories **must** be write accessible

  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.

    paster serve production.ini

  127.0.0.1:5000. This ip and port is configurable via the production.ini

  file created in previous step

- Use the admin account you created above when running ``setup-db``

- In the admin panel you can toggle ldap, anonymous, permissions settings. As

  well as edit more advanced options on users and repositories

functionality. To do this simply execute::

    paster make-rcext production.ini

for more details.

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

of ssh hosting is a planned future feature.) However you can easily use ssh in

the box" feature of mercurial_ and you can use this to access any of the

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

login accounts have the correct permissions set on the appropriate directories.

(Note that these permissions are independent of any permissions you have set up

to clone via ssh you should run::

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 against that.

Setting up Whoosh full text search

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

version 1.2 it is also possible to specify a comma separated list of

repositories (`--index-only`) to build index only on chooses repositories

skipping any other found in repos location

building index just for chosen repositories is possible with such command::

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::

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

Setting up LDAP support

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

to use LDAP, you have to install the python-ldap_ package. This package is

available via pypi, so you can install it by running

Login Attribute : required

    The LDAP record attribute that will be matched as the USERNAME or

    Filter`_ for locating the User object.  If `LDAP Filter`_ is specified as

    "LDAPFILTER", `Login Attribute`_ is specified as "uid" and the user has

    connected as "jsmith" then the `LDAP Filter`_ will be augmented as below

    The LDAP record attribute which represents the user's email address.

If all data are entered correctly, and python-ldap_ is properly installed

This means that updates of an LDAP user object may not be reflected as a

If You have problems with LDAP access and believe You entered correct

will be saved there.

Active Directory

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

is done through an LDAP or LDAPS connection to Active Directory.  The

following LDAP configuration settings are typical for using Active

Directory ::

Authentication by container or reverse-proxy

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

of users to its WSGI container, or to a reverse-proxy server through which all

clients access the application.

username that the container/proxy (Apache/Nginx/etc) authenticated and doesn't

perform the authentication itself. The authorization, however, is still done by

When a user logs in for the first time using these authentication methods,

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

permissions before the user logs in for the first time.

Container-based authentication

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

the ``REMOTE_USER`` server variable provided by the WSGI container.

After setting up your container (see `Apache's WSGI config`_), you'd need

to configure it to require authentication on the location configured for

following in the [app:main] section of your .ini file::

    container_auth_enabled = true

Proxy pass-through authentication

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

from the ``X-Forwarded-User`` request header, which should be configured to be

sent by the reverse-proxy server.

      SetEnvIf X-Url-Scheme https HTTPS=1

      AuthType Basic

      require valid-user

      RequestHeader unset X-Forwarded-User

      RequestHeader set X-Forwarded-User %{RU}e

    </Location>

the following in the [app:main] section of your .ini file::

    proxypass_auth_enabled = true

Integration with Issue trackers

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

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::

Changing default encoding

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

can be changed, simply edit default_encoding in .ini file to desired one.