=========

RhodeCode

=========

About

-----

``RhodeCode`` is a fast and powerful management tool for Mercurial_ and GIT_ 

with a built in push/pull server and full text search and code-review.

It works on http/https and has a built in permission/authentication system with 

the ability to authenticate via LDAP or ActiveDirectory. RhodeCode also provides

simple API so it's easy integrable with existing external systems.

RhodeCode is similar in some respects to github_ or bitbucket_, 

however RhodeCode can be run as standalone hosted application on your own server.

It is open source and donation ware and focuses more on providing a customized, 

self administered interface for Mercurial_ and GIT_  repositories. 

RhodeCode works on \*nix systems and Windows it is powered by a vcs_ library 

that Lukasz Balcerzak and Marcin Kuzminski created to handle multiple 

different version control systems.

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

Installation

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

Stable releases of RhodeCode are best installed via::

    easy_install rhodecode

Or::

    pip install rhodecode 

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

Please visit http://packages.python.org/RhodeCode/installation.html for

more details

RhodeCode demo

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

http://demo.rhodecode.org

The default access is anonymous but you can login to an administrative account

using the following credentials:

- username: demo

- password: demo12

Source code

-----------

The latest sources can be obtained from official RhodeCode instance

https://secure.rhodecode.org 

MIRRORS:

Issue tracker and sources at bitbucket_

http://bitbucket.org/marcinkuzminski/rhodecode

Sources at github_

https://github.com/marcinkuzminski/rhodecode

RhodeCode Features

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

- Has its own middleware to handle mercurial_ protocol requests. 

  Each request can be logged and authenticated.

- Runs on threads unlike hgweb. You can make multiple pulls/pushes simultaneous.

  Supports http/https and LDAP

- Full permissions (private/read/write/admin) and authentication per project. 

  One account for web interface and mercurial_ push/pull/clone operations.

- Have built in users groups for easier permission management

- Repository groups let you group repos and manage them easier.

- Users can fork other users repo. RhodeCode have also compare view to see

  combined changeset for all changeset made within single push.

- Build in commit-api let's you add, edit and commit files right from RhodeCode

  interface using simple editor or upload form for binaries.

- Mako templates let's you customize the look and feel of the application.

- Beautiful diffs, annotations and source code browsing all colored by pygments. 

  Raw diffs are made in git-diff format, including git_ binary-patches

- Mercurial_ branch graph and yui-flot powered graphs with zooming and statistics

- Admin interface with user/permission management. Admin activity journal, logs

  pulls, pushes, forks, registrations and other actions made by all users.

- Server side forks. It is possible to fork a project and modify it freely 

  without breaking the main repository. You can even write Your own hooks 

  and install them

- code review with notification system, inline commenting, all parsed using

  rst syntax

- rst and markdown README support for repositories  

- Full text search powered by Whoosh on the source files, and file names.

  Build in indexing daemons, with optional incremental index build

  (no external search servers required all in one application)

- Setup project descriptions and info inside built in db for easy, non 

  file-system operations

- Intelligent cache with invalidation after push or project change, provides 

  high performance and always up to date data.

- Rss / atom feeds, gravatar support, download sources as zip/tar/gz

- Optional async tasks for speed and performance using celery_  

- Backup scripts can do backup of whole app and send it over scp to desired 

  location 

- Based on pylons / sqlalchemy / sqlite / whoosh / vcs

Incoming / Plans

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

- Finer granular permissions per branch, repo group or subrepo

- pull requests and web based merges

- per line file history

- SSH based authentication with server side key management

- Commit based built in wiki system

- More statistics and graph (global annotation + some more statistics)

- Other advancements as development continues (or you can of course make 

  additions and or requests)

License

-------

``RhodeCode`` is released under the GPLv3 license.

Getting help

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

Listed bellow are various support resources that should help.

.. note::

- Join the `Google group <http://groups.google.com/group/rhodecode>`_ and ask

  any questions.

- Open an issue at `issue tracker <http://bitbucket.org/marcinkuzminski/rhodecode/issues>`_

- Join #rhodecode on FreeNode (irc.freenode.net)

  or use http://webchat.freenode.net/?channels=rhodecode for web access to irc.

- You can also follow me on twitter **@marcinkuzminski** where i often post some

  news about RhodeCode

Online documentation

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

Online documentation for the current version of RhodeCode is available at

 - http://packages.python.org/RhodeCode/

 - http://rhodecode.readthedocs.org/en/latest/index.html

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

have sphinx_ installed you can install it via the command: 

``easy_install sphinx``)

.. _virtualenv: http://pypi.python.org/pypi/virtualenv

.. _python: http://www.python.org/

.. _sphinx: http://sphinx.pocoo.org/

.. _mercurial: http://mercurial.selenic.com/

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

.. _github: http://github.com/

.. _subversion: http://subversion.tigris.org/

.. _git: http://git-scm.com/

.. _celery: http://celeryproject.org/

.. _Sphinx: http://sphinx.pocoo.org/

.. _vcs: http://pypi.python.org/pypi/vcs

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

#

# RhodeCode documentation build configuration file, created by

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

#

# All configuration values have a default; values that are commented out

# serve to show the default.

import sys

import os

import datetime

# If extensions (or modules to document with autodoc) are in another directory,

# add these directories to sys.path here. If the directory is relative to the

# documentation root, use os.path.abspath to make it absolute, like shown here.

sys.path.insert(0, os.path.abspath('..'))

# -- General configuration -----------------------------------------------------

# If your documentation needs a minimal Sphinx version, state it here.

#needs_sphinx = '1.0'

# Add any Sphinx extension module names here, as strings. They can be extensions

# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.

extensions = ['sphinx.ext.autodoc', 'sphinx.ext.doctest',

              'sphinx.ext.intersphinx', 'sphinx.ext.todo',

              'sphinx.ext.viewcode']

# Add any paths that contain templates here, relative to this directory.

templates_path = ['_templates']

# The suffix of source filenames.

source_suffix = '.rst'

# The encoding of source files.

#source_encoding = 'utf-8-sig'

# The master toctree document.

master_doc = 'index'

# General information about the project.

project = u'RhodeCode'

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.

#

# The short X.Y version.

root = os.path.dirname(os.path.dirname(__file__))

sys.path.append(root)

# The full version, including alpha/beta/rc tags.

release = __version__

# The language for content autogenerated by Sphinx. Refer to documentation

# for a list of supported languages.

#language = None

# There are two options for replacing |today|: either, you set today to some

# non-false value, then it is used:

#today = ''

# Else, today_fmt is used as the format for a strftime call.

#today_fmt = '%B %d, %Y'

# List of patterns, relative to source directory, that match files and

# directories to ignore when looking for source files.

exclude_patterns = ['_build']

# The reST default role (used for this markup: `text`) to use for all documents.

#default_role = None

# If true, '()' will be appended to :func: etc. cross-reference text.

#add_function_parentheses = True

# If true, the current module name will be prepended to all description

# unit titles (such as .. function::).

#add_module_names = True

# If true, sectionauthor and moduleauthor directives will be shown in the

# output. They are ignored by default.

#show_authors = False

# The name of the Pygments (syntax highlighting) style to use.

pygments_style = 'sphinx'

# A list of ignored prefixes for module index sorting.

#modindex_common_prefix = []

# -- Options for HTML output ---------------------------------------------------

# The theme to use for HTML and HTML Help pages.  See the documentation for

# a list of builtin themes.

html_theme = 'nature'

# Theme options are theme-specific and customize the look and feel of a theme

# further.  For a list of options available for each theme, see the

# documentation.

#html_theme_options = {}

# Add any paths that contain custom themes here, relative to this directory.

html_theme_path = ['theme']

# The name for this set of Sphinx documents.  If None, it defaults to

# "<project> v<release> documentation".

#html_title = None

# A shorter title for the navigation bar.  Default is the same as html_title.

#html_short_title = None

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

# of the sidebar.

#html_logo = None

# The name of an image file (within the static path) to use as favicon of the

# docs.  This file should be a Windows icon file (.ico) being 16x16 or 32x32

# pixels large.

#html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,

# relative to this directory. They are copied after the builtin static files,

# so a file named "default.css" will overwrite the builtin "default.css".

#html_static_path = ['_static']

# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,

# using the given strftime format.

#html_last_updated_fmt = '%b %d, %Y'

# If true, SmartyPants will be used to convert quotes and dashes to

# typographically correct entities.

#html_use_smartypants = True

# Custom sidebar templates, maps document names to template names.

#html_sidebars = {}

# Additional templates that should be rendered to pages, maps page names to

# template names.

#html_additional_pages = {}

# If false, no module index is generated.

#html_domain_indices = True

# If false, no index is generated.

#html_use_index = True

# If true, the index is split into individual pages for each letter.

#html_split_index = False

# If true, links to the reST sources are added to the pages.

#html_show_sourcelink = True

# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.

#html_show_sphinx = True

# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.

#html_show_copyright = True

# If true, an OpenSearch description file will be output, and all pages will

# contain a <link> tag referring to it.  The value of this option must be the

# base URL from which the finished HTML is served.

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

htmlhelp_basename = 'RhodeCodedoc'

# -- 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 = [

  ('index', 'RhodeCode.tex', u'RhodeCode Documentation',

   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

# For "manual" documents, if this is true, then toplevel headings are parts,

# not chapters.

#latex_use_parts = False

# If true, show page references after internal links.

#latex_show_pagerefs = False

# If true, show URL addresses after external links.

#latex_show_urls = False

# Additional stuff for the LaTeX preamble.

#latex_preamble = ''

# Documents to append as an appendix to all manuals.

#latex_appendices = []

# If false, no module index is generated.

#latex_domain_indices = True

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

# One entry per manual page. List of tuples

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

man_pages = [

    ('index', 'rhodecode', u'RhodeCode Documentation',

     [u'Marcin Kuzminski'], 1)

]

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

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

.. _index:

.. include:: ./../README.rst

Users Guide

-----------

**Installation:**

.. toctree::

   :maxdepth: 1

   installation

   setup

   upgrade

**Usage**

.. toctree::

   :maxdepth: 1

   usage/general

   usage/git_support

   usage/performance

   usage/statistics

   usage/backup

   usage/debugging

**Develop**

.. toctree::

   :maxdepth: 1

   contributing

   changelog

**API**

.. toctree::

   :maxdepth: 1

   api/api

   api/models

Other topics

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

* :ref:`genindex`

* :ref:`search`

.. _virtualenv: http://pypi.python.org/pypi/virtualenv

.. _python: http://www.python.org/

.. _django: http://www.djangoproject.com/

.. _mercurial: http://mercurial.selenic.com/

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

.. _subversion: http://subversion.tigris.org/

.. _git: http://git-scm.com/

.. _celery: http://celeryproject.org/

.. _Sphinx: http://sphinx.pocoo.org/

.. _vcs: http://pypi.python.org/pypi/vcs

.. _setup:

=====

Setup

=====

Setting up RhodeCode

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

First, you will need to create a RhodeCode configuration file. Run the 

following command to do this::

    paster make-config RhodeCode production.ini

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

  configuration file contains the various settings for RhodeCode, e.g proxy 

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

  logging.

Next, you need to create the databases used by RhodeCode. I recommend that you

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

configuration file to use this other database. RhodeCode currently supports

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

the following command::

    paster setup-rhodecode production.ini

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

RhodeCode will store all of its repositories on the current machine. After

entering this "root" path ``setup-rhodecode`` will also prompt you for a username 

and password for the initial admin account which ``setup-rhodecode`` sets 

up for you.

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

    paster setup-rhodecode production.ini --user=marcink --password=secret --email=marcin@rhodecode.org --repos=/home/marcink/my_repos

- The ``setup-rhodecode`` 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 RhodeCode will simply 

  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

  for the application. It's very important since the RhodeCode 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.

You are now ready to use RhodeCode, to run it simply execute::

    paster serve production.ini

- This command runs the RhodeCode server. The web app should be available at the 

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

  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

Optionally users can create `rcextensions` package that extends RhodeCode

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

Using RhodeCode with SSH

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

RhodeCode currently only hosts repositories using http and https. (The addition

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

parallel with RhodeCode. (Repository access via ssh is a standard "out of

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

repositories that RhodeCode is hosting. See PublishingRepositories_)

RhodeCode repository structures are kept in directories with the same name 

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

using the RhodeCode web interface.)

If your main directory (the same as set in RhodeCode settings) is for example

set to **/home/hg** and the repository you are using is named `rhodecode`, then

to clone via ssh you should run::

    hg clone ssh://user@server.com/home/hg/rhodecode

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 RhodeCode web interface, you can create an

authentication hook to connect to the rhodecode db and runs check functions for

permissions against that.

Setting up Whoosh full text search

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

Starting from version 1.1 the whoosh index can be build 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 

from the RhodeCode database.  This was required prior to 1.2.  Starting from 

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

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

	paster make-index production.ini 

For a full index rebuild use::

	paster make-index production.ini -f 

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

 paster make-index production.ini --index-only=vcs,rhodecode

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

    /path/to/python/bin/paster make-index /path/to/rhodecode/production.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 index from scratch, you can use the `-f` flag as above,

or in the admin panel you can check `build from scratch` flag.

Setting up LDAP support

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

RhodeCode starting from version 1.1 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

using easy_install::

    easy_install python-ldap

using pip::

    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.

LDAP settings are located in admin->ldap section,

Here's a typical ldap setup::

 Connection settings

 Enable LDAP          = checked

 Host                 = host.example.org

 Port                 = 389

 Account              = <account>

 Password             = <password>

 Connection Security  = LDAPS connection

 Certificate Checks   = DEMAND

 Search settings

 Base DN              = CN=users,DC=host,DC=example,DC=org

 LDAP Filter          = (&(objectClass=user)(!(objectClass=computer)))

 LDAP Search Scope    = SUBTREE

 Attribute mappings

 Login Attribute      = uid

 First Name Attribute = firstName

 Last Name Attribute  = lastName

 E-mail Attribute     = mail

.. _enable_ldap:

Enable LDAP : required

    Whether to use LDAP for authenticating users.

.. _ldap_host:

Host : required

    LDAP server hostname or IP address.

.. _Port:

Port : required

    389 for un-encrypted LDAP, 636 for SSL-encrypted LDAP.

.. _ldap_account:

Account : optional

    Only required if the LDAP server does not allow anonymous browsing of

    records.  This should be a special account for record browsing.  This

    will require `LDAP Password`_ below.

.. _LDAP Password:

Password : optional

    Only required if the LDAP server does not allow anonymous browsing of

    records.

.. _Enable LDAPS:

Connection Security : required

    Defines the connection to LDAP server

    No encryption

        Plain non encrypted connection

    LDAPS connection

        Enable ldaps connection. It will likely require `Port`_ to be set to 

        a different value (standard LDAPS port is 636). When LDAPS is enabled 

        then `Certificate Checks`_ is required.

    START_TLS on LDAP connection

        START TLS connection

.. _Certificate Checks:

Certificate Checks : optional

    How SSL certificates verification is handled - this is only useful when

    `Enable LDAPS`_ is enabled.  Only DEMAND or HARD offer full SSL security 

    while the other options are susceptible to man-in-the-middle attacks.  SSL

    certificates can be installed to /etc/openldap/cacerts so that the

    DEMAND or HARD options can be used with self-signed certificates or

    certificates that do not have traceable certificates of authority.

    NEVER

        A serve certificate will never be requested or checked.

    ALLOW

        A server certificate is requested.  Failure to provide a

        certificate or providing a bad certificate will not terminate the

        session.

    TRY

        A server certificate is requested.  Failure to provide a

        certificate does not halt the session; providing a bad certificate

        halts the session.

    DEMAND

        A server certificate is requested and must be provided and

        authenticated for the session to proceed.

    HARD

        The same as DEMAND.

.. _Base DN:

Base DN : required

    The Distinguished Name (DN) where searches for users will be performed.

    Searches can be controlled by `LDAP Filter`_ and `LDAP Search Scope`_.

.. _LDAP Filter:

LDAP Filter : optional

    A LDAP filter defined by RFC 2254.  This is more useful when `LDAP

    Search Scope`_ is set to SUBTREE.  The filter is useful for limiting

    which LDAP objects are identified as representing Users for

    authentication.  The filter is augmented by `Login Attribute`_ below.

    This can commonly be left blank.

.. _LDAP Search Scope:

LDAP Search Scope : required

    This limits how far LDAP will search for a matching object.

    BASE

        Only allows searching of `Base DN`_ and is usually not what you

        want.

    ONELEVEL

        Searches all entries under `Base DN`_, but not Base DN itself.

    SUBTREE

        Searches all entries below `Base DN`_, but not Base DN itself.

        When using SUBTREE `LDAP Filter`_ is useful to limit object

        location.

.. _Login Attribute:

Login Attribute : required        

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

    ACCOUNT used to connect to RhodeCode.  This will be added to `LDAP

    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

    ::

        (&(LDAPFILTER)(uid=jsmith))

.. _ldap_attr_firstname:

First Name Attribute : required

    The LDAP record attribute which represents the user's first name.

.. _ldap_attr_lastname:

Last Name Attribute : required

    The LDAP record attribute which represents the user's last name.

.. _ldap_attr_email:

Email Attribute : required

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

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

users should be granted access to RhodeCode with ldap accounts.  At this

time user information is copied from LDAP into the RhodeCode user database.

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

user update in RhodeCode.

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

information check out the RhodeCode logs, any error messages sent from LDAP

will be saved there.

Active Directory

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

RhodeCode can use Microsoft Active Directory for user authentication.  This

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

following LDAP configuration settings are typical for using Active

Directory ::

 Base DN              = OU=SBSUsers,OU=Users,OU=MyBusiness,DC=v3sys,DC=local

 Login Attribute      = sAMAccountName

 First Name Attribute = givenName

 Last Name Attribute  = sn

 E-mail Attribute     = mail

All other LDAP settings will likely be site-specific and should be

appropriately configured.

Authentication by container or reverse-proxy

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

Starting with version 1.3, RhodeCode supports delegating the authentication

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

clients access the application.

When these authentication methods are enabled in RhodeCode, it uses the

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

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

RhodeCode according to its settings.

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

a matching user account is created in RhodeCode with default permissions. An

administrator can then modify it using RhodeCode's admin interface.

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

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

In a container-based authentication setup, RhodeCode reads the user name from

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

RhodeCode.

In order for RhodeCode to start using the provided username, you should set the