=========

RhodeCode

=========

About

-----

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

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 

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

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/

.. _changelog:

=========

Changelog

=========

1.5.2 (**2013-01-14**)

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

news

++++

- IP restrictions for users. Each user can get a set of whitelist IP+mask for

  extra protection. Useful for buildbots etc.

- added full last changeset info to lightweight dashboard. lightweight dashboard

  is now fully functional replacement of original dashboard.

- implemented certain API calls for non-admin users.

- enabled all Markdown Extra plugins

- implemented #725 Pull Request View - Show origin repo URL

- show comments from pull requests into associated changesets

fixes

+++++

- update repoinfo script is more failsafe

- fixed #687  Lazy loaded tooltip bug with simultaneous ajax requests

- fixed #691: Notifications for pull requests: move link to top for better

  readability

- fixed #699: fix missing fork docs for API

- fixed #693 Opening changeset from pull request fails

- templating and css corrections, fixed repo switcher on chrome, updated titles

- admin menu accessible from options menu on repository view

- permissions cached queries

1.0.0rc4  (**2010-10-12**)

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

- fixed python2.5 missing simplejson imports (thanks to Jens Bäckman)

- removed cache_manager settings from sqlalchemy meta

- added sqlalchemy cache settings to ini files

- validated password length and added second try of failure on paster setup-app

- fixed setup database destroy prompt even when there was no db

1.0.0rc3 (**2010-10-11**)

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

- fixed i18n during installation.

1.0.0rc2 (**2010-10-11**)

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

- Disabled dirsize in file browser, it's causing nasty bug when dir renames 

  occure. After vcs is fixed it'll be put back again.

.. _installation_win:

Step by step Installation for Windows

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

RhodeCode step-by-step install Guide for Windows  

Target OS: Windows XP SP3 32bit English (Clean installation) 

+ All Windows Updates until 24-may-2012 

.. note::

   This installation is for 32bit systems, for 64bit windows you might need

Step1 - Install Visual Studio 2008 Express

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

Optional: You can also install MingW, but VS2008 installation is easier 

Download "Visual C++ 2008 Express Edition with SP1" from: 

http://www.microsoft.com/visualstudio/en-us/products/2008-editions/express 

(if not found or relocated, google for "visual studio 2008 express" for 

updated link) 

You can also download full ISO file for offline installation, just 

choose "All - Offline Install ISO image file" in the previous page and 

choose "Visual C++ 2008 Express" when installing. 

.. note::

  Silverlight Runtime and SQL Server 2008 Express Edition are not 

  required, you can uncheck them 

Step2 - Install Python

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

Install Python 2.x.y (x >= 5) x86 version (32bit). DO NOT USE A 3.x version.

Download Python 2.x.y from: 

http://www.python.org/download/ 

Choose "Windows Installer" (32bit version) not "Windows X86-64 

Installer". While writing this guide, the latest version was v2.7.3. 

Remember the specific major and minor version installed, because it will 

be needed in the next step. In this case, it is "2.7". 

Step3 - Install Win32py extensions

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

Download pywin32 from: 

http://sourceforge.net/projects/pywin32/files/ 

- Click on "pywin32" folder 

- Click on the first folder (in this case, Build 217, maybe newer when you try) 

- Choose the file ending with ".win32-py2.x.exe" -> x being the minor 

  version of Python you installed (in this case, 7) 

  When writing this guide, the file was: 

  http://sourceforge.net/projects/pywin32/files/pywin32/Build%20217/pywin32-217.win32-py2.7.exe/download 

Step4 - Python BIN

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

Add Python BIN folder to the path 

You have to add the Python folder to the path, you can do it manually 

(editing "PATH" environment variable) or using Windows Support Tools 

that came preinstalled in Vista/7 and can be installed in Windows XP. 

- Using support tools on WINDOWS XP: 

  If you use Windows XP you can install them using Windows XP CD and 

  navigating to \SUPPORT\TOOLS. There, execute Setup.EXE (not MSI). 

  Afterwards, open a CMD and type::

    SETX PATH "%PATH%;[your-python-path]" -M 

  Close CMD (the path variable will be updated then) 

- Using support tools on WINDOWS Vista/7: 

  Open a CMD and type::

    SETX PATH "%PATH%;[your-python-path]" /M 

Download to C:\\RhodeCode (or whatever you want) 

(the file is located at 

https://raw.github.com/pypa/virtualenv/master/virtualenv.py) 

Create a virtual Python environment in C:\\RhodeCode\\Env (or similar). To 

do so, open a CMD (Python Path should be included in Step3), navigate 

where you downloaded "virtualenv.py", and write:: 

 python virtualenv.py C:\RhodeCode\Env 

(--no-site-packages is now the default behaviour of virtualenv, no need 

to include it) 

Step7 - Install RhodeCode

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

Finally, install RhodeCode 

Close previously opened command prompt/s, and open a Visual Studio 2008 

Command Prompt (**IMPORTANT!!**). To do so, go to Start Menu, and then open 

"Microsoft Visual C++ 2008 Express Edition" -> "Visual Studio Tools" -> 

"Visual Studio 2008 Command Prompt" 

In that CMD (loaded with VS2008 PATHs) type::

  cd C:\RhodeCode\Env\Scripts (or similar) 

  activate 

The prompt will change into "(Env) C:\\RhodeCode\\Env\\Scripts" or similar 

(depending of your folder structure). Then type:: 

 pip install rhodecode 

(long step, please wait until fully complete) 

Some warnings will appear, don't worry as they are normal.

Step8 - Configuring RhodeCode

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

steps taken from http://packages.python.org/RhodeCode/setup.html 

You have to use the same Visual Studio 2008 command prompt as Step7, so 

if you closed it reopen it following the same commands (including the 

"activate" one). When ready, just type::

  - http://wiki.pylonshq.com/display/pylonscookbook/How+to+run+Pylons+as+a+Windows+service 

- Using Apache. You can investigate here:

  - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4 

Upgrading

=========

Stop running RhodeCode 

Open a CommandPrompt like in Step7 (VS2008 path + activate) and type::

 easy_install -U rhodecode 

 cd \RhodeCode\Bin 

{ backup your production.ini file now} :: 

 paster make-config RhodeCode production.ini 

(check changes and update your production.ini accordingly) ::

 paster upgrade-db production.ini (update database)

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;

    }

    server {

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

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

       # uncomment if you have nginx with chunking module compiled

       # fixes the issues of having to put postBuffer data for large git

       # pushes       

       #chunkin on;

       #error_page 411 = @my_411_error;

       #location @my_411_error {

       #    chunkin_resume;

       #}

       # uncomment if you want to serve static files by nginx

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

       location / {

            try_files $uri @rhode;

       }

       location @rhode {

            proxy_pass      http://rc;

            include         /etc/nginx/proxy.conf;

       }

    }  

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

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

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://secure.rhodecode.org/rhodecode/files/beta/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/marcinkuzminski/rhodecode/issues

 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 recommended 

that you re-check the content after the automerge.

.. note::

   Please always make sure your .ini files are up to date. Often errors are

   caused by missing params added in new versions.

It is also recommended that you rebuild the whoosh index after upgrading since 

the new whoosh version could introduce some incompatible index changes. Please

Read the changelog to see if there were any changes to whoosh.

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,

and will always recheck the settings of the application, if there are no new 

options that need to be set.

You may find it helpful to clear out your log file so that new errors are 

readily apparent::

 echo > rhodecode.log

Once that is complete, you may now start your upgraded Rhodecode Instance::

 service rhodecode start

Or::

 paster serve /var/www/rhodecode/production.ini

.. note::

   If you're using Celery, make sure you restart all instances of it after

   upgrade.

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

.. _general:

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

General RhodeCode usage

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

Repository deleting

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

Currently when admin/owner deletes a repository, RhodeCode does not physically

delete a repository from filesystem, it renames it in a special way so it's

not possible to push,clone or access repository. It's worth a notice that,

even if someone will be given administrative access to RhodeCode and will 

delete a repository You can easy restore such action by restoring `rm__<date>`

Follow current branch in file view

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

In file view when this checkbox is checked the << and >> arrows will jump

to changesets within the same branch currently viewing. So for example

if someone is viewing files at 'beta' branch and marks `follow current branch`

checkbox the << and >> buttons will only show him revisions for 'beta' branch

Compare view from changelog

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

Checkboxes in compare view allow users to view combined compare view. You can

only show the range between the first and last checkbox (no cherry pick).

Clicking more than one checkbox will activate a link in top saying

`Show selected changes <from-rev> -> <to-rev>` clicking this will bring

Compare view is also available from the journal on pushes having more than

one changeset

Non changeable repository urls

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

Due to complicated nature of repository grouping, often urls of repositories

can change.

example::

  #before

  http://server.com/repo_name

  # after insertion to test_group group the url will be

  http://server.com/test_group/repo_name

This can be an issue for build systems and any other hardcoded scripts, moving

repository to a group leads to a need for changing external systems. To 

overcome this RhodeCode introduces a non changable replacement url. It's 

simply an repository ID prefixed with `_` above urls are also accessible as::

  http://server.com/_<ID>

Trending source files

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

Trending source files are calculated based on pre defined dict of known

types and extensions. If You miss some extension or Would like to scan some

custom files it's possible to add new types in `LANGUAGES_EXTENSIONS_MAP` dict

located in `/rhodecode/lib/celerylib/tasks.py`

Cloning remote repositories

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

RhodeCode has an ability to clone remote repos from given remote locations.

Currently it support following options:

- hg  -> hg clone

- svn -> hg clone

- git -> git clone

.. note::

If you need to clone repositories that are protected via basic auth, you

might pass the url with stored credentials inside eg. 

using given credentials. Please take a note that they will be stored as

plaintext inside the database. RhodeCode will remove auth info when showing the 

clone url in summary page.

: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

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