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

Welcome to RhodeCode (RhodiumCode) documentation!

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

``RhodeCode`` (formerly hg-app) is a Pylons framework based Mercurial repository 

browser/management tool with a built in push/pull server and full text search.

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

the ability to authenticate via LDAP.

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 soon GIT) repositories. 

RhodeCode is powered by a vcs_ library that Lukasz Balcerzak and I created to 

handle multiple different version control systems.

RhodeCode uses `Semantic Versioning <http://semver.org/>`_

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

Source code

-----------

The latest source for RhodeCode can be obtained from official RhodeCode instance

https://hg.rhodecode.org 

http://bitbucket.org/marcinkuzminski/rhodecode

Installation

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

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

RhodeCode Features

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

- Has it's own middleware to handle mercurial_ protocol requests. 

  Each request can be logged and authenticated.

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

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

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

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

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

- 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

- Async tasks for speed and performance using celery_ (works without them too)  

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

  location 

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

.. include:: ./docs/screenshots.rst

Incoming / Plans

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

- Project grouping

- User groups/teams

- SSH based authentication with server side key management

- Code review (probably based on hg-review)

- Full git_ support, with push/pull server (currently in beta tests)

- Redmine integration

- Public accessible activity feeds

- Commit based built in wiki system

- Clone points and cloning from remote repositories into RhodeCode

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

Mailing group Q&A

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

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

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.

Online documentation

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

Online documentation for the current version of RhodeCode is available at

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

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

   make html

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

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

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

.. _GPL: http://www.gnu.org/licenses/gpl.html

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

.. _changelog:

Changelog

=========

1.1.5 (**2011-03-17**)

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

news

----

- basic windows support, by exchanging pybcrypt into sha256 for windows only

  highly inspired by idea of mantis406

fixes

-----

- fixed sorting by author in main page

- fixed crashes with diffs on binary files

- fixed #131 problem with boolean values for LDAP

- fixed #122 mysql problems thanks to striker69 

- fixed problem with errors on calling raw/raw_files/annotate functions 

  with unknown revisions

- fixed returned rawfiles attachment names with international character

- cleaned out docs, big thanks to Jason Harris

1.1.4 (**2011-02-19**)

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

news

----

fixes

-----

- fixed formencode import problem on settings page, that caused server crash

  when that page was accessed as first after server start

- journal fixes

- fixed option to access repository just by entering http://server/<repo_name> 

1.1.3 (**2011-02-16**)

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

news

----

- implemented #102 allowing the '.' character in username

- added option to access repository just by entering http://server/<repo_name>

- celery task ignores result for better performance

fixes

-----

- fixed ehlo command and non auth mail servers on smtp_lib. Thanks to 

  apollo13 and Johan Walles

- small fixes in journal

- fixed problems with getting setting for celery from .ini files

- registration, password reset and login boxes share the same title as main 

  application now

- fixed #113: to high permissions to fork repository

- fixed problem with '[' chars in commit messages in journal

- removed issue with space inside renamed repository after deletion

- db transaction fixes when filesystem repository creation failed

- fixed #106 relation issues on databases different than sqlite

- fixed static files paths links to use of url() method

1.1.2 (**2011-01-12**)

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

news

----

fixes

-----

- fixes #98 protection against float division of percentage stats

- fixed graph bug

- forced webhelpers version since it was making troubles during installation 

1.1.1 (**2011-01-06**)

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

news

----

- added force https option into ini files for easier https usage (no need to

  set server headers with this options)

- small css updates

fixes

-----

- fixed #96 redirect loop on files view on repositories without changesets

- fixed #97 unicode string passed into server header in special cases (mod_wsgi)

  and server crashed with errors

- fixed large tooltips problems on main page

- fixed #92 whoosh indexer is more error proof

1.1.0 (**2010-12-18**)

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

"""

    rhodecode.__init__

    ~~~~~~~~~~~~~~~~~~

    RhodeCode, a web based repository management based on pylons

    versioning implementation: http://semver.org/

    :created_on: Apr 9, 2010

    :author: marcink

    :copyright: (C) 2009-2011 Marcin Kuzminski <marcin@python-works.com>    

    :license: GPLv3, see COPYING for more details.

"""

# This program is free software; you can redistribute it and/or

# modify it under the terms of the GNU General Public License

# as published by the Free Software Foundation; version 2

# of the License or (at your opinion) any later version of the license.

# 

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

# 

# You should have received a copy of the GNU General Public License

# along with this program; if not, write to the Free Software

# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,

# MA  02110-1301, USA.

import platform

__version__ = '.'.join((str(each) for each in VERSION[:4]))

__dbversion__ = 2 #defines current db version for migrations

__platform__ = platform.system()

try:

    from rhodecode.lib.utils import get_current_revision

    _rev = get_current_revision()

except ImportError:

    #this is needed when doing some setup.py operations

    _rev = False

if len(VERSION) > 3 and _rev:

    __version__ += ' [rev:%s]' % _rev[0]

def get_version():

    """Returns shorter version (digit parts only) as string."""

    return '.'.join((str(each) for each in VERSION[:3]))

BACKENDS = {

    'hg': 'Mercurial repository',

   #'git': 'Git repository',

}

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

"""

    rhodecode.lib.auth

    ~~~~~~~~~~~~~~~~~~

    authentication and permission libraries

    :created_on: Apr 4, 2010

    :copyright: (c) 2010 by marcink.

    :license: LICENSE_NAME, see LICENSE_FILE for more details.

"""

# This program is free software; you can redistribute it and/or

# modify it under the terms of the GNU General Public License

# as published by the Free Software Foundation; version 2

# of the License or (at your opinion) any later version of the license.

# 

# This program is distributed in the hope that it will be useful,

# but WITHOUT ANY WARRANTY; without even the implied warranty of

# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

# GNU General Public License for more details.

# 

# You should have received a copy of the GNU General Public License

# along with this program; if not, write to the Free Software

# Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,

# MA  02110-1301, USA.

import random

import logging

import traceback

from decorator import decorator

from pylons import config, session, url, request

from pylons.controllers.util import abort, redirect

from pylons.i18n.translation import _

    from hashlib import sha256

    import bcrypt

from rhodecode.lib import str2bool

from rhodecode.lib.exceptions import LdapPasswordError, LdapUsernameError

from rhodecode.lib.utils import get_repo_slug

from rhodecode.lib.auth_ldap import AuthLdap

from rhodecode.model import meta

from rhodecode.model.user import UserModel

from rhodecode.model.db import Permission, RepoToPerm, Repository, \

    User, UserToPerm

log = logging.getLogger(__name__)

class PasswordGenerator(object):

    """This is a simple class for generating password from

        different sets of characters

        usage:

        passwd_gen = PasswordGenerator()

        #print 8-letter password containing only big and small letters of alphabet

        print passwd_gen.gen_password(8, passwd_gen.ALPHABETS_BIG_SMALL)        

    """

    ALPHABETS_NUM = r'''1234567890'''#[0]

    ALPHABETS_SMALL = r'''qwertyuiopasdfghjklzxcvbnm'''#[1]

    ALPHABETS_BIG = r'''QWERTYUIOPASDFGHJKLZXCVBNM'''#[2]

    ALPHABETS_SPECIAL = r'''`-=[]\;',./~!@#$%^&*()_+{}|:"<>?'''    #[3]

    ALPHABETS_FULL = ALPHABETS_BIG + ALPHABETS_SMALL + ALPHABETS_NUM + ALPHABETS_SPECIAL#[4]

    ALPHABETS_ALPHANUM = ALPHABETS_BIG + ALPHABETS_SMALL + ALPHABETS_NUM#[5]

    ALPHABETS_BIG_SMALL = ALPHABETS_BIG + ALPHABETS_SMALL

    ALPHABETS_ALPHANUM_BIG = ALPHABETS_BIG + ALPHABETS_NUM#[6]

    ALPHABETS_ALPHANUM_SMALL = ALPHABETS_SMALL + ALPHABETS_NUM#[7]

    def __init__(self, passwd=''):

        self.passwd = passwd

    def gen_password(self, len, type):

        self.passwd = ''.join([random.choice(type) for _ in xrange(len)])

        return self.passwd

class RhodeCodeCrypto(object):

    @classmethod

    def hash_string(cls, str_):

        """

        Cryptographic function used for password hashing based on pybcrypt

        or pycrypto in windows

        :param password: password to hash

        """

            return sha256(str_).hexdigest()

            return bcrypt.hashpw(str_, bcrypt.gensalt(10))

        else:

            raise Exception('Unknown or unsupported platform %s' % __platform__)

    @classmethod

    def hash_check(cls, password, hashed):

        """

        Checks matching password with it's hashed value, runs different

        implementation based on platform it runs on

        :param password: password

        :param hashed: password in hashed form

        """

        if __platform__ == 'Windows':

            return sha256(password).hexdigest() == hashed

        elif __platform__ in ('Linux', 'Darwin'):

            return bcrypt.hashpw(password, hashed) == hashed

        else:

            raise Exception('Unknown or unsupported platform %s' % __platform__)

def get_crypt_password(password):

    return RhodeCodeCrypto.hash_string(password)

def check_password(password, hashed):

    return RhodeCodeCrypto.hash_check(password, hashed)

def authfunc(environ, username, password):

    """

    Dummy authentication function used in Mercurial/Git/ and access control,

    :param environ: needed only for using in Basic auth

    """

    return authenticate(username, password)

def authenticate(username, password):

    """

    Authentication function used for access control,

    firstly checks for db authentication then if ldap is enabled for ldap

    authentication, also creates ldap user if not in database

    :param username: username

    :param password: password

    """

    user_model = UserModel()

    user = user_model.get_by_username(username, cache=False)

    log.debug('Authenticating user using RhodeCode account')

    if user is not None and user.is_ldap is False:

        if user.active:

            if user.username == 'default' and user.active:

                log.info('user %s authenticated correctly as anonymous user',

                         username)

                return True

            elif user.username == username and check_password(password, user.password):

                log.info('user %s authenticated correctly', username)

                return True

        else:

            log.warning('user %s is disabled', username)

    else:

        log.debug('Regular authentication failed')

        user_obj = user_model.get_by_username(username, cache=False,

                                            case_insensitive=True)

        if user_obj is not None and user_obj.is_ldap is False:

            log.debug('this user already exists as non ldap')

            return False

        from rhodecode.model.settings import SettingsModel

        ldap_settings = SettingsModel().get_ldap_settings()

        #======================================================================

        # FALLBACK TO LDAP AUTH IN ENABLE                

        #======================================================================

        if str2bool(ldap_settings.get('ldap_active')):

            log.debug("Authenticating user using ldap")

            kwargs = {

                  'server':ldap_settings.get('ldap_host', ''),

                  'base_dn':ldap_settings.get('ldap_base_dn', ''),

                  'port':ldap_settings.get('ldap_port'),

                  'bind_dn':ldap_settings.get('ldap_dn_user'),

                  'bind_pass':ldap_settings.get('ldap_dn_pass'),

                  'use_ldaps':str2bool(ldap_settings.get('ldap_ldaps')),

                  'ldap_version':3,

                  }

            log.debug('Checking for ldap authentication')

            try:

                aldap = AuthLdap(**kwargs)

                res = aldap.authenticate_ldap(username, password)

                log.debug('Got ldap response %s', res)

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

<head>

    <title>${next.title()}</title>

    <link rel="icon" href="${h.url('/images/icons/database_gear.png')}" type="image/png" />

    <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />

    <meta name="robots" content="index, nofollow"/>

    <!-- stylesheets -->

    ${self.css()}

    <!-- scripts -->

    ${self.js()}

</head>

<body>

    <!-- header -->

    <div id="header">

        <!-- user -->

        <ul id="logged-user">

	            <li class="first">

	                <div class="gravatar">

	                    <img alt="gravatar" src="${h.gravatar_url(c.rhodecode_user.email,20)}" />

	                </div>

		            <div class="account">

		            %if c.rhodecode_user.username == 'default':

                        %if h.HasPermissionAny('hg.admin', 'hg.register.auto_activate', 'hg.register.manual_activate')(): 

                            ${h.link_to('anonymous',h.url('register'),title='%s %s'%(c.rhodecode_user.name,c.rhodecode_user.lastname))}

                        %else:

                            ${h.link_to('anonymous',h.url('#'),title='%s %s'%(c.rhodecode_user.name,c.rhodecode_user.lastname))}

                        %endif		            

                    %else:                        		            

		            	${h.link_to(c.rhodecode_user.username,h.url('admin_settings_my_account'),title='%s %s'%(c.rhodecode_user.name,c.rhodecode_user.lastname))}

		            %endif

		            </div>	

	            </li>

	            <li>

	               <a href="${h.url('home')}">${_('Home')}</a>

	            </li>

	            %if c.rhodecode_user.username != 'default':

                <li>

                   <a href="${h.url('journal')}">${_('Journal')}</a> 

                   ##(${c.unread_journal})</a>

                </li>

                %endif

                %if c.rhodecode_user.username == 'default':

                    <li class="last highlight">${h.link_to(u'Login',h.url('login_home'))}</li>

                %else:

                    <li class="last highlight">${h.link_to(u'Log Out',h.url('logout_home'))}</li>

                %endif

        </ul>

        <!-- end user -->

        <div id="header-inner" class="title top-left-rounded-corner top-right-rounded-corner">

            <!-- logo -->

            <div id="logo">

                <h1><a href="${h.url('home')}">${c.rhodecode_name}</a></h1>

            </div>

            <!-- end logo -->

            <!-- menu -->

            ${self.page_nav()}

            <!-- quick -->

        </div>

    </div>     

    <!-- end header -->

	<!-- CONTENT -->

	<div id="content"> 

        <div class="flash_msg">

            <% messages = h.flash.pop_messages() %>

            % if messages:

            <ul id="flash-messages">

                % for message in messages:

                <li class="${message.category}_msg">${message}</li>

                % endfor

            </ul>

            % endif

        </div>	    

	    <div id="main"> 

	        ${next.main()}

	    </div>

	</div> 

    <!-- END CONTENT -->

	<!-- footer -->

	<div id="footer">

	   <div id="footer-inner" class="title bottom-left-rounded-corner bottom-right-rounded-corner">

	       <div>

	           <p class="footer-link">${h.link_to(_('Submit a bug'),h.url('bugtracker'))}</p>

		       <p class="footer-link">${h.link_to(_('GPL license'),h.url('gpl_license'))}</p>

		       <p class="footer-link-right"><a href="${h.url('rhodecode_official')}">RhodeCode</a> ${c.rhodecode_version} &copy; 2010-2011 by Marcin Kuzminski</p>

	       </div>

	   </div>

        <script type="text/javascript">

        function tooltip_activate(){

        ${h.tooltip.activate()}

        }

        tooltip_activate();

        </script>

	</div>

	<!-- end footer -->

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

    <head>

        <title>Error - ${c.error_message}</title>

        <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />

	    %if c.redirect_time:

	        <meta http-equiv="refresh" content="${c.redirect_time}; url=${c.url_redirect}"/>

	    %endif        

		<link rel="icon" href="${h.url('/images/icons/database_gear.png')}" type="image/png" />

        <meta name="robots" content="index, nofollow"/>

        <!-- stylesheets -->

        <link rel="stylesheet" type="text/css" href="${h.url('/css/style.css')}" media="screen" />

	    <style type="text/css">

	     #main_div{

	       border: 0px solid #000;

	       width: 500px;

	       margin: auto;

	       text-align: center;

	       margin-top: 200px;

	       font-size: 1.6em;

	     }

	     .error_message{

	        text-align: center;

	        color:#003367;

	        font-size: 1.6em;

	        margin:10px;

	     }

	    </style>

    </head>

    <body>

        <div id="login">

            <div class="table">            

				<div id="main_div">

				    <div style="font-size:2.0em;margin: 10px">${c.rhodecode_name}</div>

					<h1 class="error_message">${c.error_message}</h1>

					<p>${c.error_explanation}</p>

			        %if c.redirect_time:

			            <p>${_('You will be redirected to %s in %s seconds') % (c.redirect_module,c.redirect_time)}</p>

				    %endif		

				</div>

            </div>

            <!-- end login -->

        </div>

    </body>

</html>

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

    <head>

        <title>${_('Sign In')} - ${c.rhodecode_name}</title>

        <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />

        <link rel="icon" href="${h.url("/images/icons/database_gear.png")}" type="image/png" />

        <meta name="robots" content="index, nofollow"/>

        <!-- stylesheets -->

        <link rel="stylesheet" type="text/css" href="${h.url('/css/style.css')}" media="screen" />

    </head>

    <body>

        <div id="login">

        <div class="flash_msg">

            <% messages = h.flash.pop_messages() %>

            % if messages:

            <ul id="flash-messages">

                % for message in messages:

                <li class="${message.category}_msg">${message}</li>

                % endfor

            </ul>

            % endif

        </div>          

            <!-- login -->

            <div class="title top-left-rounded-corner top-right-rounded-corner">

                <h5>${_('Sign In to')} ${c.rhodecode_name}</h5>

            </div>

            <div class="inner">            

                ${h.form(h.url.current(came_from=c.came_from))}

                <div class="form">

                    <!-- fields -->

                    <div class="fields">

                        <div class="field">

                            <div class="label">

                                <label for="username">${_('Username')}:</label>

                            </div>

                            <div class="input">

                                ${h.text('username',class_='focus',size=40)}

                            </div>

                        </div>                     

                        <div class="field">

                            <div class="label">

                                <label for="password">${_('Password')}:</label>

                            </div>

                            <div class="input">

                                ${h.password('password',class_='focus',size=40)}

                            </div>

                        </div>

                        ##<div class="field">

                        ##    <div class="checkbox">

                        ##        <input type="checkbox" id="remember" name="remember" />

                        ##        <label for="remember">Remember me</label>

                        ##    </div>

                        ##</div>

                        <div class="buttons">

                            ${h.submit('sign_in','Sign In',class_="ui-button")}

                        </div>

                    </div>

                    <!-- end fields -->

                    <!-- links -->

                    <div class="links">

                        ${h.link_to(_('Forgot your password ?'),h.url('reset_password'))}

                        %if h.HasPermissionAny('hg.admin', 'hg.register.auto_activate', 'hg.register.manual_activate')():

	                         / 

	                        ${h.link_to(_("Don't have an account ?"),h.url('register'))}

                        %endif

                    </div>

                    <!-- end links -->

                </div>

                ${h.end_form()}

            </div>

            <!-- end login -->

        </div>

    </body>

</html>

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

    <head>

        <title>${_('Reset You password')} - ${c.rhodecode_name}</title>

        <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />

        <link rel="icon" href="${h.url("/images/hgicon.png")}" type="image/png" />

        <meta name="robots" content="index, nofollow"/>

        <!-- stylesheets -->

        <link rel="stylesheet" type="text/css" href="${h.url('/css/style.css')}" media="screen" />

    </head>

    <body>

		<div id="register">

			<div class="title top-left-rounded-corner top-right-rounded-corner">

				<h5>${_('Reset You password to')} ${c.rhodecode_name}</h5>

			</div>

			<div class="inner">

			    ${h.form(url('password_reset'))}

			    <div class="form">

			        <!-- fields -->

			        <div class="fields">

			             <div class="field">

			                <div class="label">

			                    <label for="email">${_('Email address')}:</label>

			                </div>

			                <div class="input">

			                    ${h.text('email')}

			                </div>

			             </div>

			            <div class="buttons">

				            <div class="nohighlight">

				              ${h.submit('send','Reset my password',class_="ui-button")}

							  	<div class="activation_msg">${_('Your new password will be send to matching email address')}</div>

				            </div>

			            </div>             

			    	</div>

			    </div>

			    ${h.end_form()}

			</div>    

	    </div>

    </body>

</html>

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

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

    <head>

        <title>${_('Sign Up')} - ${c.rhodecode_name}</title>

        <meta http-equiv="Content-Type" content="text/html;charset=utf-8" />

        <link rel="icon" href="${h.url("/images/hgicon.png")}" type="image/png" />

        <meta name="robots" content="index, nofollow"/>

        <!-- stylesheets -->

        <link rel="stylesheet" type="text/css" href="${h.url('/css/style.css')}" media="screen" />

    </head>

    <body>

		<div id="register">