RhodeCode uses `PEP386 versioning <http://www.python.org/dev/peps/pep-0386/>`_

Installation

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

Stable releases of RhodeCode are best installed via::

Or::

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

more details

Source code

-----------

Online documentation

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

Online documentation for the current version of RhodeCode is available at

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

   make html

(You need to have sphinx_ installed to build the documentation. If you don't

qthelp:

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

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

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

	@echo

	@echo "Build finished. The epub file is in $(BUILDDIR)/epub."

===

API

===

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

To make this operation easier, starting from version 1.7.0 there's a white list

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,

        ChangesetController:changeset_raw,

        FilesController:raw,

        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 ACCESS

.. note::

    api_key can be found in your user account page

    {

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

        "result": "<result>"|null, # JSON formatted result, null if any errors

        "error": "null"|<error_message> # JSON formatted error (if any)

    }

and result will be null.

API CLIENT

++++++++++

will be available.

To get started quickly simply run::

  kallithea-api _create_config --apikey=<youapikey> --apihost=<your.kallithea.server>

after that simply run any api command for example get_repo::

 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}

Ups looks like we forgot to add an argument

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

    {'error': None,

     'id': 39,

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

rescan_repos

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

Dispatch rescan repositories action. If remove_obsolete is set

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

rights.

INPUT::

    id : <id_for_response>

    error :  null

show_ip

-------

defined IP addresses for given user.

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

rights.

INPUT::

# -*- 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.

#

# Note that not all possible configuration values are present in this

# autogenerated file.

#source_encoding = 'utf-8-sig'

# The master toctree document.

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

# |version| and |release|, also used in various other places throughout the

# built documents.

#

#html_use_opensearch = ''

# This is the file name suffix for HTML files (e.g. ".xhtml").

#html_file_suffix = None

# Output file base name for HTML help builder.

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

# The paper size ('letter' or 'a4').

#latex_paper_size = 'letter'

# The font size ('10pt', '11pt' or '12pt').

#latex_font_size = '10pt'

# 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'),

]

# The name of an image file (relative to this directory) to place at the top of

# the title page.

#latex_logo = None

# -- Options for manual page output --------------------------------------------

# One entry per manual page. List of tuples

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

man_pages = [

     [u'Marcin Kuzminski'], 1)

]

# Example configuration for intersphinx: refer to the Python standard library.

intersphinx_mapping = {'http://docs.python.org/': None}

.. _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

command to install/verify all required packages, and prepare development

enviroment.

    paster serve test.ini --pid-file=test.pid --daemon

    RC_WHOOSH_TEST_DISABLE=1 RC_NO_TMP_PATH=1 nosetests -x kallithea/tests/other/test_vcs_operations.py

    kill -9 $(cat test.pid)

| Thank you for any contributions!

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

.. _installation:

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

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

Step by step installation example for Windows

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

Step by step installation example for Linux

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

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

Alternative very detailed installation instructions for Ubuntu Server with

celery, indexer and daemon scripts: https://gist.github.com/4546398

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

**Message Broker**

- preferred is `RabbitMq <http://www.rabbitmq.com/>`_

Step by step Installation for Windows

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

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

+ All Windows Updates until 24-may-2012

.. note::

    SETX PATH "%PATH%;[your-python-path]" /M

  Please substitute [your-python-path] with your Python installation path.

  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

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

Install Virtual Env for Python

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

"Microsoft Visual C++ 2008 Express Edition" -> "Visual Studio Tools" ->

"Visual Studio 2008 Command Prompt"

%comspec% /k ""C:\Program Files (x86)\Microsoft Visual Studio 9.0\VC\vcvarsall.bat"" amd64

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

(free) or similar text editor, as it handles well the EndOfLine

character differences between Unix and Windows

(http://notepad-plus-plus.org/)

For the sake of simplicity lets 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

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)

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.

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

just type::

 paster serve production.ini

Open yout web server, and go to http://127.0.0.1:5000

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/

  - 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

=========

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)

if "%1" == "qthelp" (

	%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp

	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

)

if "%1" == "devhelp" (

	%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp

	echo.

=====

Setup

=====

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

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.

setup process can be fully automated, example for lazy::

    paster setup-db production.ini --user=nn --password=secret --email=nn@your.kallithea.server --repos=/home/nn/my_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

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

  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

functionality. To do this simply execute::

    paster make-rcext production.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

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