language: python

python:

  - "2.5"

  - "2.6"

  - "2.7"

env:  

  - TEST_DB=sqlite:////tmp/rhodecode_test.sqlite

  - TEST_DB=mysql://root@127.0.0.1/rhodecode_test

  - TEST_DB=postgresql://postgres@127.0.0.1/rhodecode_test

services:

  - mysql

  - postgresql

# command to install dependencies

before_script:

  - mysql -e 'create database rhodecode_test;'

  - psql -c 'create database rhodecode_test;' -U postgres

  - git --version

before_install:

  - sudo apt-get remove git

  - sudo add-apt-repository ppa:pdoes/ppa -y

  - sudo apt-get update -y

  - sudo apt-get install git -y

install:

  - pip install mysql-python psycopg2 mock unittest2

  - pip install . --use-mirrors

# command to run tests

script: nosetests

notifications:

    email:

        - marcinkuz@gmail.com

branches:

  only:

    - master

=========

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

-----------

The latest sources can be obtained from https://kallithea-scm.org/repos/kallithea

MIRRORS:

Issue tracker and sources at bitbucket_

https://bitbucket.org/conservancy/kallithea

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

- Open an issue at `issue tracker <https://bitbucket.org/conservancy/kallithea/issues>`_

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

 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

following in the [app:main] section of your .ini file::

    container_auth_enabled = true

Proxy pass-through authentication

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

In a proxy pass-through authentication setup, RhodeCode reads the user name

from the ``X-Forwarded-User`` request header, which should be configured to be

sent by the reverse-proxy server.

After setting up your proxy solution (see `Apache virtual host reverse proxy example`_,

`Apache as subdirectory`_ or `Nginx virtual host example`_), you'd need to

configure the authentication and add the username in a request header named

``X-Forwarded-User``.

For example, the following config section for Apache sets a subdirectory in a

reverse-proxy setup with basic auth::

    <Location /<someprefix> >

      ProxyPass http://127.0.0.1:5000/<someprefix>

      ProxyPassReverse http://127.0.0.1:5000/<someprefix>

      SetEnvIf X-Url-Scheme https HTTPS=1

      AuthType Basic

      AuthName "RhodeCode authentication"

      AuthUserFile /home/web/rhodecode/.htpasswd

      require valid-user

      RequestHeader unset X-Forwarded-User

      RewriteEngine On

      RewriteCond %{LA-U:REMOTE_USER} (.+)

      RewriteRule .* - [E=RU:%1]

      RequestHeader set X-Forwarded-User %{RU}e

    </Location>

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

the following in the [app:main] section of your .ini file::

    proxypass_auth_enabled = true

.. note::

   If you enable proxy pass-through authentication, make sure your server is

   only accessible through the proxy. Otherwise, any client would be able to

   forge the authentication header and could effectively become authenticated

   using any account of their liking.

Integration with Issue trackers

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

RhodeCode provides a simple integration with issue trackers. It's possible

to define a regular expression that will fetch issue id stored in commit

messages and replace that with an url to this issue. To enable this simply

uncomment following variables in the ini file::

    issue_pat = (?:^#|\s#)(\w+)

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

    issue_prefix = #

`issue_pat` is the regular expression that will fetch issues from commit messages.

Default regex will match issues in format of #<number> eg. #300.

Matched issues will be replace with the link specified as `issue_server_link`

{id} will be replaced with issue id, and {repo} with repository name.

Since the # is striped `issue_prefix` is added as a prefix to url.

`issue_prefix` can be something different than # if you pass

ISSUE- as issue prefix this will generate an url in format::

  <a href="https://myissueserver.com/example_repo/issue/300">ISSUE-300</a>

Hook management

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

Hooks can be managed in similar way to this used in .hgrc files.

To access hooks setting click `advanced setup` on Hooks section of Mercurial

Settings in Admin.

There are 4 built in hooks that cannot be changed (only enable/disable by

checkboxes on previos section).

To add another custom hook simply fill in first section with

<name>.<hook_type> and the second one with hook path. Example hooks

can be found at *rhodecode.lib.hooks*.

Changing default encoding

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

By default RhodeCode uses utf8 encoding, starting from 1.3 series this

can be changed, simply edit default_encoding in .ini file to desired one.

This affects many parts in rhodecode including committers names, filenames,

encoding of commit messages. In addition RhodeCode can detect if `chardet`

library is installed. If `chardet` is detected RhodeCode will fallback to it

when there are encode/decode errors.

Setting Up Celery

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

Since version 1.1 celery is configured by the rhodecode ini configuration files.

Simply set use_celery=true in the ini file then add / change the configuration

variables inside the ini file.

Remember that the ini files use the format with '.' not with '_' like celery.

So for example setting `BROKER_HOST` in celery means setting `broker.host` in

the config file.

In order to start using celery run::

 paster celeryd <configfile.ini>

.. note::

   Make sure you run this command from the same virtualenv, and with the same

   user that rhodecode runs.

HTTPS support

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

There are two ways to enable https:

- Set HTTP_X_URL_SCHEME in your http server headers, than rhodecode will

  recognize this headers and make proper https redirections

- Alternatively, change the `force_https = true` flag in the ini configuration

  to force using https, no headers are needed than to enable https

Nginx virtual host example

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

Sample config for nginx using proxy::

    upstream rc {

        server 127.0.0.1:5000;

        # add more instances for load balancing

        #server 127.0.0.1:5001;

        #server 127.0.0.1:5002;

    }

    ## gist alias

    server {

       listen          443;

       server_name     gist.myserver.com;

       access_log      /var/log/nginx/gist.access.log;

       error_log       /var/log/nginx/gist.error.log;

       ssl on;

       ssl_certificate     gist.rhodecode.myserver.com.crt;

       ssl_certificate_key gist.rhodecode.myserver.com.key;

       ssl_session_timeout 5m;

       ssl_protocols SSLv3 TLSv1;

       ssl_ciphers DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:EDH-RSA-DES-CBC3-SHA:AES256-SHA:DES-CBC3-SHA:AES128-SHA:RC4-SHA:RC4-MD5;

       ssl_prefer_server_ciphers on;

       rewrite ^/(.+)$ https://rhodecode.myserver.com/_admin/gists/$1;

       rewrite (.*)    https://rhodecode.myserver.com/_admin/gists;

    }

    server {

       listen          443;

       server_name     rhodecode.myserver.com;

       access_log      /var/log/nginx/rhodecode.access.log;

       error_log       /var/log/nginx/rhodecode.error.log;

       ssl on;

       ssl_certificate     rhodecode.myserver.com.crt;

       ssl_certificate_key rhodecode.myserver.com.key;

       ssl_session_timeout 5m;

       ssl_protocols SSLv3 TLSv1;

       ssl_ciphers DHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA:EDH-RSA-DES-CBC3-SHA:AES256-SHA:DES-CBC3-SHA:AES128-SHA:RC4-SHA:RC4-MD5;

       ssl_prefer_server_ciphers on;

       ## uncomment root directive if you want to serve static files by nginx

       ## requires static_files = false in .ini file

       #root /path/to/installation/rhodecode/public;

       include         /etc/nginx/proxy.conf;

       location / {

            try_files $uri @rhode;

       }

       location @rhode {

            proxy_pass      http://rc;

       }

    }

Here's the proxy.conf. It's tuned so it will not timeout on long

pushes or large pushes::

    proxy_redirect              off;

    proxy_set_header            Host $host;

    ## needed for container auth

    #proxy_set_header            REMOTE_USER $remote_user;

    #proxy_set_header            X-Forwarded-User $remote_user;

    proxy_set_header            X-Url-Scheme $scheme;

    proxy_set_header            X-Host $http_host;

    proxy_set_header            X-Real-IP $remote_addr;

    proxy_set_header            X-Forwarded-For $proxy_add_x_forwarded_for;

    proxy_set_header            Proxy-host $proxy_host;

    proxy_buffering             off;

    proxy_connect_timeout       7200;

    proxy_send_timeout          7200;

    proxy_read_timeout          7200;

    proxy_buffers               8 32k;

    client_max_body_size        1024m;

    client_body_buffer_size     128k;

    large_client_header_buffers 8 64k;

Apache virtual host reverse proxy 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 /<someprefix> >

      ProxyPass http://127.0.0.1:5000/<someprefix>

      ProxyPassReverse http://127.0.0.1:5000/<someprefix>

      SetEnvIf X-Url-Scheme https HTTPS=1

    </Location>

Besides the regular apache setup you will need to add the following line

into [app:main] section of 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>

then change <someprefix> into your chosen prefix

Apache's WSGI config

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

Alternatively, RhodeCode can be set up with Apache under mod_wsgi. For

that, you'll need to:

- Install mod_wsgi. If using a Debian-based distro, you can install

  the package libapache2-mod-wsgi::

    aptitude install libapache2-mod-wsgi

- Enable mod_wsgi::

    a2enmod wsgi

- Create a wsgi dispatch script, like the one below. Make sure you

  check the paths correctly point to where you installed RhodeCode

  and its Python Virtual Environment.

- Enable the WSGIScriptAlias directive for the wsgi dispatch script,

  as in the following example. Once again, check the paths are

  correctly specified.

Here is a sample excerpt from an Apache Virtual Host configuration file::

    WSGIDaemonProcess pylons \

        threads=4 \

        python-path=/home/web/rhodecode/pyenv/lib/python2.6/site-packages

    WSGIScriptAlias / /home/web/rhodecode/dispatch.wsgi

    WSGIPassAuthorization On

.. note::

   when running apache as root please add: `user=www-data group=www-data`

   into above configuration

.. note::

   Running RhodeCode in multiprocess mode in apache is not supported,

   make sure you don't specify `processes=num` directive in the config

Example wsgi dispatch script::

    import os

    os.environ["HGENCODING"] = "UTF-8"

    os.environ['PYTHON_EGG_CACHE'] = '/home/web/rhodecode/.egg-cache'

    # sometimes it's needed to set the curent dir

    os.chdir('/home/web/rhodecode/')

    import site

    site.addsitedir("/home/web/rhodecode/pyenv/lib/python2.6/site-packages")

    from paste.deploy import loadapp

    from paste.script.util.logging_config import fileConfig

    fileConfig('/home/web/rhodecode/production.ini')

    application = loadapp('config:/home/web/rhodecode/production.ini')

Note: when using mod_wsgi you'll need to install the same version of

Mercurial that's inside RhodeCode's virtualenv also on the system's Python

environment.

Other configuration files

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

Some example init.d scripts can be found in init.d directory::

  https://kallithea-scm.org/repos/kallithea/files/tip/init.d/

.. _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/conservancy/kallithea/issues

.. _troubleshooting:

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

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.

    Try out great celery docs for further help.

|

: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. Very often

    Apache, Nginx or other http servers kill the connection due to to large

    body.

|

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

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

|

:Q: **Git fails on push/pull?**

:A: Make sure you're using an wsgi http server that can handle chunked encoding

    such as `waitress` or `gunicorn`

|

:Q: **How i use hooks in RhodeCode?**

:A: It's easy if they are python hooks just use advanced link in hooks section

    in Admin panel, that works only for Mercurial. If you want to use githooks,

    just install proper one in repository eg. create file in

    `/gitrepo/hooks/pre-receive`. You can also use RhodeCode-extensions to

    connect to callback hooks, for both Git and Mercurial.

|

:Q: **RhodeCode is slow for me, how can i make it faster?**

:A: See the :ref:`performance` section

|

:Q: **UnicodeDecodeError on Apache mod_wsgi**

:A: Please read: https://docs.djangoproject.com/en/dev/howto/deployment/wsgi/modwsgi/#if-you-get-a-unicodeencodeerror

|

:Q: **Requests hanging on Windows**

:A: Please try out with disabled Antivirus software, there are some known problems with Eset Anitivirus. Make sure

    you have installed latest windows patches (especially KB2789397)

.. _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/conservancy/kallithea/issues