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

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 uses `Semantic Versioning <http://semver.org/>`_

RhodeCode demo

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

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

using the following credentials:

- username: demo

- password: demo

Source code

-----------

Rarely updated source code and issue tracker is available at bitbcuket

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.

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

- 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

(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/

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

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

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

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

news

----

- rewrite of internals for vcs >=0.1.10

- uses mercurial 1.7 with dotencode disabled for maintaining compatibility 

  with older clients

- anonymous access, authentication via ldap

- performance upgrade for cached repos list - each repository has it's own 

  cache that's invalidated when needed.

- performance upgrades on repositories with large amount of commits (20K+)

- main page quick filter for filtering repositories

- user dashboards with ability to follow chosen repositories actions

- sends email to admin on new user registration

- added cache/statistics reset options into repository settings

- more detailed action logger (based on hooks) with pushed changesets lists

  and options to disable those hooks from admin panel

- introduced new enhanced changelog for merges that shows more accurate results

- new improved and faster code stats (based on pygments lexers mapping tables, 

  showing up to 10 trending sources for each repository. Additionally stats

.. _contributing:

Contributing to RhodeCode

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

If you would like to contribute to RhodeCode, please contact me, any help is

greatly appreciated!

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

https://bitbucket.org/marcinkuzminski/rhodecode and then make your changes to

To run RhodeCode in a development version you always need to install the tip

version of RhodeCode and the VCS library.

| Thank you for any contributions!

.. _index:

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

Documentation

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

**Installation:**

.. toctree::

   :maxdepth: 1

   installation

   setup

   upgrade

**Usage**

.. toctree::

   :maxdepth: 1

   enable_git

   statistics

**Develop**

.. toctree::

   :maxdepth: 1

   contributing

   changelog

**API**

.. toctree::

   :maxdepth: 2

   api/index

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/

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

.. _installation:

Installation

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

``RhodeCode`` is written entirely in Python. In order to gain maximum performance

there are some third-party you must install. When RhodeCode is used 

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

recommended one is rabbitmq_ to make the async tasks work.

Of course RhodeCode works in sync mode also and then you do not have to install

Installing RhodeCode from Cheese Shop

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

Rhodecode requires python version 2.5 or higher.

The easiest way to install ``rhodecode`` is to run::

    easy_install rhodecode

Or::

    pip install rhodecode

If you prefer to install RhodeCode manually simply grab latest release from

http://pypi.python.org/pypi/rhodecode, decompress the archive and run::

    python setup.py install

Step by step installation example

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

- Assuming you have installed virtualenv_ create a new virtual environment using virtualenv:: 

    virtualenv --no-site-packages /var/www/rhodecode-venv

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

   RhodeCode.  If you do not specify ``--no-site-packages``,

   it's possible that RhodeCode will not install properly into

   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.

- this will install new virtualenv_ into `/var/www/rhodecode-venv`. 

- Activate the virtualenv_ by running::

    source /var/www/rhodecode-venv/bin/activate

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

- Make a folder for rhodecode somewhere on the filesystem for example::

    mkdir /var/www/rhodecode

- Run this command to install rhodecode::

    easy_install rhodecode 

- This will install rhodecode together with pylons and all other required python

  libraries

Requirements for Celery (optional)

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

.. note::

   Installing message broker and using celery is optional, RhodeCode will

   work perfectly fine without them.

**Message Broker** 

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

- A possible alternative is `Redis <http://code.google.com/p/redis/>`_

For installation instructions you can visit: 

http://ask.github.com/celery/getting-started/index.html.

This is a very nice tutorial on how to start using celery_ with rabbitmq_

You can now proceed to :ref:`setup`

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

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

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

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

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

.. _rabbitmq: http://www.rabbitmq.com/

    proxy_send_timeout          3600;

    proxy_read_timeout          3600;

    proxy_buffer_size           16k;

    proxy_buffers               4 16k;

    proxy_busy_buffers_size     64k;

    proxy_temp_file_write_size  64k;

Also, when using root path with nginx you might set the static files to false

in the production.ini file::

    [app:main]

      use = egg:rhodecode

      full_stack = true

      static_files = false

      lang=en

      cache_dir = %(here)s/data

In order to not have the statics served by the application. This improves speed.

Apache virtual host example

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

Here is a sample configuration file for apache using proxy::

    <VirtualHost *:80>

            ServerName hg.myserver.com

            ServerAlias hg.myserver.com

            <Proxy *>

              Order allow,deny

              Allow from all

            </Proxy>

            #important !

            #Directive to properly generate url (clone url) for pylons

            ProxyPreserveHost On

            #rhodecode 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://wiki.pylonshq.com/display/pylonscookbook/Apache+as+a+reverse+proxy+for+Pylons

Apache as subdirectory

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

Apache subdirectory part::

    <Location /rhodecode>

      ProxyPass http://127.0.0.1:59542/rhodecode

      ProxyPassReverse http://127.0.0.1:59542/rhodecode

      SetEnvIf X-Url-Scheme https HTTPS=1

    </Location> 

Besides the regular apache setup you will need to add the following to your .ini file::

    filter-with = proxy-prefix

Add the following at the end of the .ini file::

    [filter:proxy-prefix]

    use = egg:PasteDeploy#prefix

    prefix = /<someprefix> 

Apache's example FCGI config

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

TODO !

Other configuration files

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

Some example init.d scripts can be found here, for debian and gentoo:

https://rhodeocode.org/rhodecode/files/tip/init.d

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.6/site-packages/rhodecode/public

:Q: **Can't install celery/rabbitmq**

:A: Don't worry RhodeCode works without them too. No extra setup is required.

|

:Q: **Long lasting push timeouts?**

:A: Make sure you set a longer timeouts in your proxy/fcgi settings, timeouts

    are caused by https server and not RhodeCode.

:Q: **Large pushes timeouts?**

:A: Make sure you set a proper max_body_size for the http server.

|

:Q: **Apache doesn't pass basicAuth on pull/push?**

:A: Make sure you added `WSGIPassAuthorization true`.

For further questions search the `Issues tracker`_, or post a message in the `google group rhodecode`_

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

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

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

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

.. _rabbitmq: http://www.rabbitmq.com/

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

.. _mercurial-server: http://www.lshift.net/mercurial-server.html

.. _PublishingRepositories: http://mercurial.selenic.com/wiki/PublishingRepositories

.. _Issues tracker: https://bitbucket.org/marcinkuzminski/rhodecode/issues

.. _google group rhodecode: http://groups.google.com/group/rhodecode

.. _upgrade:

Upgrade

=======

Upgrading from Cheese Shop

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

.. note::

The easiest way to upgrade ``rhodecode`` is to run::

 easy_install -U rhodecode

Or::

 pip install --upgrade rhodecode

Then make sure you run the following command from the installation directory::

 paster make-config RhodeCode production.ini

This will display any changes made by the new version of RhodeCode to your

current configuration. It will try to perform an automerge. It's always better

.. note::

   The next steps only apply to upgrading from non bugfix releases eg. from

   any minor or major releases. Bugfix releases (eg. 1.1.2->1.1.3) will 

   not have any database schema changes or whoosh library updates.

The final step is to upgrade the database. To do this simply run::

    paster upgrade-db production.ini

This will upgrade the schema and update some of the defaults in the database,

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

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

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

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

.. _rabbitmq: http://www.rabbitmq.com/

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

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

__dbversion__ = 2 #defines current db version for migrations

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

}

################################################################################

################################################################################

# RhodeCode - Pylons environment configuration                                 #

#                                                                              # 

# The %(here)s variable will be replaced with the parent directory of this file#

################################################################################

[DEFAULT]

debug = true

################################################################################

## Uncomment and replace with the address which should receive                ## 

## any error reports after application crash                                  ##

## Additionally those settings will be used by RhodeCode mailing system       ##

################################################################################

#email_to = admin@localhost

#error_email_from = paste_error@localhost

#app_email_from = rhodecode-noreply@localhost

#error_message =

#smtp_server = mail.server.com

#smtp_username = 

#smtp_password = 

#smtp_port = 

#smtp_use_tls = false

#smtp_use_ssl = true

[server:main]

##nr of threads to spawn

threadpool_workers = 5

##max request before thread respawn

threadpool_max_requests = 10

##option to use threads of process

use_threadpool = true

use = egg:Paste#http

host = 127.0.0.1

port = 5000

[app:main]

use = egg:rhodecode

full_stack = true

static_files = true

lang=en

cache_dir = %(here)s/data

index_dir = %(here)s/data/index

app_instance_uuid = ${app_instance_uuid}

cut_off_limit = 256000

force_https = false 

####################################

###        CELERY CONFIG        ####

####################################

use_celery = false

broker.host = localhost

broker.vhost = rabbitmqhost

broker.port = 5672

broker.user = rabbitmq

broker.password = qweqwe

celery.imports = rhodecode.lib.celerylib.tasks

celery.result.backend = amqp

celery.result.dburi = amqp://

celery.result.serialier = json

#celery.send.task.error.emails = true

#celery.amqp.task.result.expires = 18000

celeryd.concurrency = 2

#celeryd.log.file = celeryd.log

celeryd.log.level = debug

#tasks will never be sent to the queue, but executed locally instead.

celery.always.eager = false

####################################

###         BEAKER CACHE        ####

####################################

beaker.cache.data_dir=%(here)s/data/cache/data

beaker.cache.lock_dir=%(here)s/data/cache/lock

beaker.cache.regions=super_short_term,short_term,long_term,sql_cache_short,sql_cache_med,sql_cache_long

beaker.cache.super_short_term.type=memory

beaker.cache.super_short_term.expire=10

beaker.cache.short_term.type=memory

beaker.cache.short_term.expire=60

beaker.cache.long_term.type=memory

beaker.cache.long_term.expire=36000

beaker.cache.sql_cache_short.type=memory

beaker.cache.sql_cache_short.expire=10

beaker.cache.sql_cache_med.type=memory

beaker.cache.sql_cache_med.expire=360

beaker.cache.sql_cache_long.type=file

beaker.cache.sql_cache_long.expire=3600

####################################

###       BEAKER SESSION        ####

####################################