=========

RhodeCode

=========

About

-----

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

with a built in push/pull server, 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

-----------

MIRRORS:

Issue tracker and sources at bitbucket_

RhodeCode Features

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

- Has its own middleware to handle mercurial_ and git_ protocol requests.

  Each request is authenticated and logged together with IP address.

- Build for speed and performance. You can make multiple pulls/pushes simultaneous.

  Proven to work with 1000s of repositories and users

- Supports http/https, LDAP, AD, proxy-pass authentication.

- Full permissions (private/read/write/admin) together with IP restrictions for each repository,

  additional explicit forking, repositories group and repository creation permissions.

- User groups for easier permission management.

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

  permission delegation features, so you can delegate groups management.

- Users can fork other users repos, and compare them at any time.

- Built in Gist functionality for sharing code snippets.

- Integrates easily with other systems, with custom created mappers you can connect it to almost

  any issue tracker, and with an JSON-RPC API you can make much more

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

  web interface using simple editor or upload binary files using simple form.

- Powerfull pull-request driven review system with inline commenting,

  changeset statuses, and notification system.

- Importing and syncing repositories from remote locations for GIT_, Mercurial_ and  SVN.

- 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 for both VCS systems, including GIT_ binary-patches

- Mercurial_ and Git_ DAG graphs and yui-flot powered graphs with zooming and statistics

  to track activity for repositories

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

- rst and markdown README support for repositories.

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

  Build in indexing daemons, with optional incremental index build

  (no external search servers required all in one application)

- Setup project descriptions/tags 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, downloadable 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, or subrepo

- Web based merges for pull requests

- Tracking history for each lines in files

- Simple issue tracker

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

   Please try to read the documentation before posting any issues, especially

   the **troubleshooting section**

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

  any questions.

- 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

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

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

# RhodeCode - Pylons environment configuration                                 #

#                                                                              #

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

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

[DEFAULT]

debug = true

pdebug = false

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

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

#email_prefix = [RhodeCode]

#smtp_server = mail.server.com

#smtp_username =

#smtp_password =

#smtp_port =

#smtp_use_tls = false

#smtp_use_ssl = true

## Specify available auth parameters here (e.g. LOGIN PLAIN CRAM-MD5, etc.)

#smtp_auth =

[server:main]

## PASTE ##

#use = egg:Paste#http

## nr of worker threads to spawn

#threadpool_workers = 5

## max request before thread respawn

#threadpool_max_requests = 10

## option to use threads of process

#use_threadpool = true

## WAITRESS ##

use = egg:waitress#main

## number of worker threads

threads = 5

## MAX BODY SIZE 100GB

max_request_body_size = 107374182400

## use poll instead of select, fixes fd limits, may not work on old

## windows systems.

#asyncore_use_poll = True

## GUNICORN ##

#use = egg:gunicorn#main

## number of process workers. You must set `instance_id = *` when this option

## is set to more than one worker

#workers = 1

## process name

#proc_name = rhodecode

## type of worker class, one of sync, eventlet, gevent, tornado

## recommended for bigger setup is using of of other than sync one

#worker_class = sync

#max_requests = 5

## ammount of time a worker can handle request before it gets killed and

## restarted

#timeout = 3600

## UWSGI ##

## run with uwsgi --ini-paste-logged <inifile.ini>

#[uwsgi]

#socket = /tmp/uwsgi.sock

#master = true

#http = 0.0.0.0:5000

## set as deamon and redirect all output to file

#daemonize = ./uwsgi_rhodecode.log

## master process PID

#pidfile = ./uwsgi_rhodecode.pid

## stats server with workers statistics, use uwsgitop

## for monitoring, `uwsgitop 127.0.0.1:1717`

#stats = 127.0.0.1:1717

#memory-report = true

## log 5XX errors

#log-5xx = true

## Set the socket listen queue size.

#listen = 256

## Gracefully Reload workers after the specified amount of managed requests

## (avoid memory leaks).

#max-requests = 1000

## enable large buffers

#buffer-size=65535

## socket and http timeouts ##

#http-timeout=3600

#socket-timeout=3600

## Log requests slower than the specified number of milliseconds.

#log-slow = 10

## Exit if no app can be loaded.

#need-app = true

## Set lazy mode (load apps in workers instead of master).

#lazy = true

## scaling ##

## set cheaper algorithm to use, if not set default will be used

#cheaper-algo = spare

## minimum number of workers to keep at all times

#cheaper = 1

## number of workers to spawn at startup

#cheaper-initial = 1

## maximum number of workers that can be spawned

#workers = 4

## how many workers should be spawned at a time

#cheaper-step = 1

## COMMON ##

host = 0.0.0.0

port = 5000

## prefix middleware for rc

#[filter:proxy-prefix]

#use = egg:PasteDeploy#prefix

#prefix = /<your-prefix>

[app:main]

use = egg:rhodecode

## enable proxy prefix middleware

#filter-with = proxy-prefix

full_stack = true

static_files = true

## Optional Languages

## en, fr, ja, pt_BR, zh_CN, zh_TW, pl

lang = en

cache_dir = %(here)s/data

index_dir = %(here)s/data/index

## perform a full repository scan on each server start, this should be

## set to false after first startup, to allow faster server restarts.

initial_repo_scan = true

## uncomment and set this path to use archive download cache

#archive_cache_dir = /tmp/tarballcache

## change this to unique ID for security

app_instance_uuid = rc-production

## cut off limit for large diffs (size in bytes)

cut_off_limit = 256000

## use cache version of scm repo everywhere

vcs_full_cache = true

## force https in RhodeCode, fixes https redirects, assumes it's always https

force_https = false

## use Strict-Transport-Security headers

use_htsts = false

## number of commits stats will parse on each iteration

commit_parse_limit = 25

## use gravatar service to display avatars

use_gravatar = true

## path to git executable

git_path = git

## git rev filter option, --all is the default filter, if you need to

## hide all refs in changelog switch this to --branches --tags

git_rev_filter=--all

## RSS feed options

rss_cut_off_limit = 256000

rss_items_per_page = 10

rss_include_diff = false

## options for showing and identifying changesets

show_sha_length = 12

show_revision_number = true

## gist URL alias, used to create nicer urls for gist. This should be an

## url that does rewrites to _admin/gists/<gistid>.

## example: http://gist.rhodecode.org/{gistid}. Empty means use the internal

## RhodeCode url, ie. http[s]://rhodecode.server/_admin/gists/<gistid>

gist_alias_url =

## white list of API enabled controllers. This allows to add list of

## controllers to which access will be enabled by api_key. eg: to enable

## api access to raw_files put `FilesController:raw`, to enable access to patches

## add `ChangesetController:changeset_patch`. This list should be "," separated

## Syntax is <ControllerClass>:<function>. Check debug logs for generated names

## Recommended settings bellow are commented out:

api_access_controllers_whitelist =

#    ChangesetController:changeset_patch,

#    ChangesetController:changeset_raw,

#    FilesController:raw,

#    FilesController:archivefile

## alternative_gravatar_url allows you to use your own avatar server application

## the following parts of the URL will be replaced

## {email}        user email

## {md5email}     md5 hash of the user email (like at gravatar.com)

## {size}         size of the image that is expected from the server application

## {scheme}       http/https from RhodeCode server

## {netloc}       network location from RhodeCode server

#alternative_gravatar_url = http://myavatarserver.com/getbyemail/{email}/{size}

#alternative_gravatar_url = http://myavatarserver.com/getbymd5/{md5email}?s={size}

## container auth options

container_auth_enabled = false

proxypass_auth_enabled = false

## default encoding used to convert from and to unicode

## can be also a comma seperated list of encoding in case of mixed encodings

default_encoding = utf8

## overwrite schema of clone url

## available vars:

## scheme - http/https

## user - current user

## pass - password

## netloc - network location

## path - usually repo_name

#clone_uri = {scheme}://{user}{pass}{netloc}{path}

## issue tracker for RhodeCode (leave blank to disable, absent for default)

## issue tracking mapping for commits messages

## comment out issue_pat, issue_server, issue_prefix to enable

## pattern to get the issues from commit messages

## default one used here is #<numbers> with a regex passive group for `#`

## {id} will be all groups matched from this pattern

issue_pat = (?:\s*#)(\d+)

## server url to the issue, each {id} will be replaced with match

## fetched from the regex and {repo} is replaced with full repository name

## including groups {repo_name} is replaced with just name of repo

issue_server_link = https://myissueserver.com/{repo}/issue/{id}

## prefix to add to link to indicate it's an url

## #314 will be replaced by <issue_prefix><id>

issue_prefix = #

## issue_pat, issue_server_link, issue_prefix can have suffixes to specify

## multiple patterns, to other issues server, wiki or others

## below an example how to create a wiki pattern

#  #wiki-some-id -> https://mywiki.com/some-id

#issue_pat_wiki = (?:wiki-)(.+)

#issue_server_link_wiki = https://mywiki.com/{id}

#issue_prefix_wiki = WIKI-

## instance-id prefix

## a prefix key for this instance used for cache invalidation when running

## multiple instances of rhodecode, make sure it's globally unique for

## all running rhodecode instances. Leave empty if you don't use it

instance_id =

## alternative return HTTP header for failed authentication. Default HTTP

## response is 401 HTTPUnauthorized. Currently HG clients have troubles with

## handling that. Set this variable to 403 to return HTTPForbidden

auth_ret_code =

## locking return code. When repository is locked return this HTTP code. 2XX

## codes don't break the transactions while 4XX codes do

lock_ret_code = 423

## allows to change the repository location in settings page

allow_repo_location_change = True

## allows to setup custom hooks in settings page

allow_custom_hooks_settings = True

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

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

celeryd.max.tasks.per.child = 1

## 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.super_short_term.key_length = 256

beaker.cache.short_term.type=memory

beaker.cache.short_term.expire=60

beaker.cache.short_term.key_length = 256

beaker.cache.long_term.type=memory

beaker.cache.long_term.expire=36000

beaker.cache.long_term.key_length = 256

beaker.cache.sql_cache_short.type=memory

beaker.cache.sql_cache_short.expire=10

beaker.cache.sql_cache_short.key_length = 256

beaker.cache.sql_cache_med.type=memory

beaker.cache.sql_cache_med.expire=360

beaker.cache.sql_cache_med.key_length = 256

beaker.cache.sql_cache_long.type=file

beaker.cache.sql_cache_long.expire=3600

beaker.cache.sql_cache_long.key_length = 256

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

###       BEAKER SESSION        ####

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

## Type of storage used for the session, current types are

## dbm, file, memcached, database, and memory.

## The storage uses the Container API

## that is also used by the cache system.

## db session ##

#beaker.session.type = ext:database

#beaker.session.sa.url = postgresql://postgres:qwe@localhost/rhodecode

#beaker.session.table_name = db_session

## encrypted cookie client side session, good for many instances ##

#beaker.session.type = cookie

## file based cookies (default) ##

#beaker.session.type = file

beaker.session.key = rhodecode

beaker.session.secret = develop-rc-uytcxaz

## Secure encrypted cookie. Requires AES and AES python libraries

## you must disable beaker.session.secret to use this

#beaker.session.encrypt_key = <key_for_encryption>

#beaker.session.validate_key = <validation_key>

## sets session as invalid if it haven't been accessed for given amount of time

beaker.session.timeout = 2592000

beaker.session.httponly = true

#beaker.session.cookie_path = /<your-prefix>

## uncomment for https secure cookie

beaker.session.secure = false

## auto save the session to not to use .save()

beaker.session.auto = False

## default cookie expiration time in seconds `true` expire at browser close ##

#beaker.session.cookie_expires = 3600

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

## ERROR HANDLING SYSTEMS ##

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

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

### [errormator] ###

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

## Errormator is tailored to work with RhodeCode, see

## http://errormator.com for details how to obtain an account

## you must install python package `errormator_client` to make it work

## errormator enabled

errormator = false

errormator.server_url = https://api.errormator.com

errormator.api_key = YOUR_API_KEY

## TWEAK AMOUNT OF INFO SENT HERE

## enables 404 error logging (default False)

errormator.report_404 = false

## time in seconds after request is considered being slow (default 1)

errormator.slow_request_time = 1

## record slow requests in application

## (needs to be enabled for slow datastore recording and time tracking)

errormator.slow_requests = true

## enable hooking to application loggers

# errormator.logging = true

## minimum log level for log capture

# errormator.logging.level = WARNING

## send logs only from erroneous/slow requests

## (saves API quota for intensive logging)

errormator.logging_on_error = false

## list of additonal keywords that should be grabbed from environ object

## can be string with comma separated list of words in lowercase

## (by default client will always send following info:

## 'REMOTE_USER', 'REMOTE_ADDR', 'SERVER_NAME', 'CONTENT_TYPE' + all keys that

## start with HTTP* this list be extended with additional keywords here

errormator.environ_keys_whitelist =

## list of keywords that should be blanked from request object

## can be string with comma separated list of words in lowercase

## (by default client will always blank keys that contain following words

## 'password', 'passwd', 'pwd', 'auth_tkt', 'secret', 'csrf'

## this list be extended with additional keywords set here

errormator.request_keys_blacklist =

## list of namespaces that should be ignores when gathering log entries

## can be string with comma separated list of namespaces

## (by default the client ignores own entries: errormator_client.client)

errormator.log_namespace_blacklist =

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

### [sentry] ###

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

## sentry is a alternative open source error aggregator

## you must install python packages `sentry` and `raven` to enable

sentry.dsn = YOUR_DNS

sentry.servers =

sentry.name =

sentry.key =

sentry.public_key =

sentry.secret_key =

sentry.project =

sentry.site =

sentry.include_paths =

sentry.exclude_paths =

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

## WARNING: *THE LINE BELOW MUST BE UNCOMMENTED ON A PRODUCTION ENVIRONMENT*  ##

## Debug mode will enable the interactive debugging tool, allowing ANYONE to  ##

## execute malicious code after an exception is raised.                       ##

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

#set debug = false

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

###       LOGVIEW CONFIG       ###

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

logview.sqlalchemy = #faa

logview.pylons.templating = #bfb

logview.pylons.util = #eee

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

### DB CONFIGS - EACH DB WILL HAVE IT'S OWN CONFIG    ###

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

#sqlalchemy.db1.url = sqlite:///%(here)s/rhodecode.db?timeout=30

sqlalchemy.db1.url = postgresql://postgres:qweqwe@localhost/rhodecode

#sqlalchemy.db1.url = mysql://root:qweqwe@localhost/rhodecode

sqlalchemy.db1.echo = false

sqlalchemy.db1.pool_recycle = 3600

sqlalchemy.db1.convert_unicode = true

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

### LOGGING CONFIGURATION   ####

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

[loggers]

keys = root, routes, rhodecode, sqlalchemy, beaker, templates, whoosh_indexer

[handlers]

keys = console, console_sql

[formatters]

keys = generic, color_formatter, color_formatter_sql

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

## LOGGERS ##

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

[logger_root]

level = NOTSET

handlers = console

[logger_routes]

level = DEBUG

handlers =

qualname = routes.middleware

## "level = DEBUG" logs the route matched and routing variables.

propagate = 1

[logger_beaker]

level = DEBUG

handlers =

qualname = beaker.container

propagate = 1

[logger_templates]

level = INFO

handlers =

qualname = pylons.templating

propagate = 1

[logger_rhodecode]

level = DEBUG

handlers =

qualname = rhodecode

propagate = 1

[logger_sqlalchemy]

level = INFO

handlers = console_sql

qualname = sqlalchemy.engine

propagate = 0

[logger_whoosh_indexer]

level = DEBUG

handlers =

qualname = whoosh_indexer

propagate = 1

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

## HANDLERS ##

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

[handler_console]

class = StreamHandler

args = (sys.stderr,)

level = DEBUG

formatter = color_formatter

[handler_console_sql]

class = StreamHandler

args = (sys.stderr,)

level = DEBUG

formatter = color_formatter_sql

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

## FORMATTERS ##

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

[formatter_generic]

format = %(asctime)s.%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s

datefmt = %Y-%m-%d %H:%M:%S

[formatter_color_formatter]

class=rhodecode.lib.colored_formatter.ColorFormatter

format= %(asctime)s.%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s

datefmt = %Y-%m-%d %H:%M:%S

[formatter_color_formatter_sql]

class=rhodecode.lib.colored_formatter.ColorFormatterSql

format= %(asctime)s.%(msecs)03d %(levelname)-5.5s [%(name)s] %(message)s

datefmt = %Y-%m-%d %H:%M:%S

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

RhodeCode repository on bitbucket_

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,

please send me a pull request.

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

required libs. Simply clone rhodecode and switch to beta branch::

after downloading/pulling RhodeCode make sure you run::

    python setup.py develop

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

enviroment.

There are two files in the directory production.ini and developement.ini copy

the `development.ini` file as rc.ini (which is excluded from version controll)

and put all your changes like db connection or server port in there.

After finishing your changes make sure all tests passes ok. You can run

the testsuite running ``nosetest`` from the project root, or if you use tox

run tox for python2.5-2.7 with multiple database test. When using `nosetests`

test.ini file is used and by default it uses sqlite for tests, edit this file

to change your testing enviroment.

There's a special set of tests for push/pull operations, you can runn them using::

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

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

    kill -9 $(cat test.pid)

| Thank you for any contributions!

|  Marcin

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

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

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