Skip to content

Latest commit

 

History

History
executable file
·
259 lines (162 loc) · 14.5 KB

README.mkd

File metadata and controls

executable file
·
259 lines (162 loc) · 14.5 KB

Redmine Git Hosting Plugin (v0.4.2)

A ChiliProject / Redmine plugin which makes configuring your own git hosting easy. This plugin allows straightforward management of gitolite and associated public keys, the git daemon, and integrates code from Scott Schacon's "grack" utility to provide Git Smart HTTP access. Git repositories are automatically created when the repository is created in redmine. There is also an option to automatically create a git repository for a project, when the project is created. Caching functionality is also implemented to speed page-load times for viewing git repositories.

Configuration Strategy

One major problem when configuring ChiliProject/Redmine + Git is how the git repositories are accessed, and in particular setting permissions properly. This plugin solves this problem by allowing the web server/rails user to run git via sudo. A previous version of this plugin (see ssh branch) requires the configuration of git to run through ssh, but using sudo to allow the web server user to run commands as the git user is much faster. To configure your sudoers file to allow your web server user to run commands as git, and your git user to run commands as the web server user add these two lines to your sudoers file (run visudo to edit this file):

www-data        ALL=(git)       NOPASSWD:ALL
git             ALL=(www-data)  NOPASSWD:ALL

This assumes www-data is your web server user, and git is your git user (the user gitolite is installed under). This will allow www-data to execute commands as git without prompting for a password and git to execute commands as www-data without prompting for a password. No other access (e.g. no root access, permissions to run commands as other users) are granted by these lines. These lines are only there to facilitate communication between the web server user and the git user, no other users, keeping the system secure.

Note that this guide refers to the "web server user" as the user under which Rails is being, which is usually (but not always) the same as the user that runs the main web server. If you are running Rails under a different user, follow these instructions using that user, not the one for the main web server.

Step-By-Step configuration instructions

(1) Install gitolite. The details of gitolite installation are beyond the scope of these instructions, and there are plenty of guides elsewhere on how to do this. For the purposes of this tutorial, we will assume that gitolite has been installed for user "git", and you have an ssh key called "git_gitolite_admin_id_rsa" (and corresponding public key) for which access to the gitolite-admin repository has been granted.

(2) If you want to enable anonymous access to your repositories via the git:// protocol you will need to install the git-daemon. The details of this are beyond the scope of the tutorial as well (and again there are lots of available guides out there). This step is optional -- if you don't want to enable anonymous access you can skip it.

(3) Run visudo (you will need root permissions to run this) and set the necessary lines in your sudoers file, listed above. Assuming your web server is run as www-data and gitolite is installed as git, you need to add this to your sudoers file:

www-data        ALL=(git)       NOPASSWD:ALL
git             ALL=(www-data)  NOPASSWD:ALL

(4) In the root of your Redmine/ChiliProject rails directory -- the Redmine/ChiliProject root, not the plugin root, and not the public directory -- create a directory called .ssh, and copy the "gitolite_admin_id_rsa" private key and the "gitolite_admin_id_rsa.pub" files from step one into this directory. Then change the owner of these files to www-data and the permissions to 600 for the private key and 644 for the public key:

cd [redmine_rails_root]
mkdir .ssh
cp [somewhere-or-other]/gitolite_admin_id_rsa     .ssh/gitolite_admin_id_rsa
cp [somewhere-or-other]/gitolite_admin_id_rsa.pub .ssh/gitolite_admin_id_rsa.pub

chown www-data -R .ssh
chmod 700 .ssh
chmod 600 .ssh/gitolite_admin_id_rsa
chmod 644 .ssh/gitolite_admin_id_rsa.pub

(5) Clone the redmine_git_hosting plugin into the vendor/plugins subdirectory of your Redmine/ChiliProject root directory:

cd vendor/plugins
git clone https://github.com/ericpaulbishop/redmine_git_hosting.git
rm -rf redmine_git_hosting/.git
cd ../..

(6) It is best to set several plugin variables BEFORE you run the db:migrate_plugins task in step 7. In particular it is important that the httpServer, gitServer, gitUser, gitRepositoryBasePath, gitoliteIdentityFile and gitoliteIdentityPublicKeyFile variables are set correctly. To adjust these variables, open an editor and edit [redmine_rails_root]/vendor/plugins/redmine_git_hosting/init.rb file. Starting on line 22 you will see the settings definitions you should edit.

The httpServer variable should be set to the url used to access your redmine site, e.g. www.my-own-personal-git-host-server.com. Note that if Redmine is not installed in the site root this should include the path to your redmine root, e.g. www.my-own-personal-git-host-server.com/path/to/redmine

The gitServer will usually be the same as the the httpServer variable -- this is the server name to use to access the gitolite repositories via ssh. This should be the hostname only, so this will be different from httpServer if Redmine is not installed in the site root. In other words, even if redmine is installed in www.my-own-personal-git-host-server.com/path/to/redmine, gitServer should be set to www.my-own-personal-git-host-server.com

The gitUser is the user under which gitolite is installed

The gitRepositoryBasePath is the path relative to the git user root where the repositories are located. This should always end in a file separator, e.g. '/'. Since gitolite always uses repositories/ as the default place for repositories you probably shouldn't have to change this.

If you followed the above directions you will not need to modify the gitoliteIdentityFile or gitoliteIdentityPublicKeyFile variables -- these specify the path to the private/public key files for accessing the gitolite admin repository.

These variables can be modified at a later time in the Administration => Plugins => Redmine Git Hosting Plugin configuration page. However to ensure that the database migration from your existing repositories goes smoothly it is best to modify these variables now.

(7) Run the rake db:migrate_plugins task to update the database. You will need to do this once for every rails environment you have configured (e.g. production, development, testing). For the production environment run:

RAILS_ENV=production rake db:migrate_plugins

(8) Unless you want to access your repositories exclusively via Smart HTTP users will need to set a public key to connect via SSH. To do this, open a browser, login to ChiliProject/Redmine and follow the "My Account" Link in the upper right-hand corner of the page. The right-hand column contains controls for adding your public key(s).

Keys should be unique, that is, the keys you set in ChiliProject / Redmine should not already exist in the gitolite repo. In particular, do not re-use the key you set as the gitolite admin key.

(9) The plugin is now configured, but you may now want to set some additional settings on the Administration => Plugins => Redmine Git Hosting Plugin page.

Automatically Initialize Git Repositories For New Projects can be enabled to automatically create a new git repository every time you create a new project. You won't have to create the project, and then create the repository -- this will be done all it one step. However, if you have both git and svn (or hg, or cvs etc.) repositories, this may cause problems so it is disabled by default.

Delete Git Repository When Project Is Deleted can be enabled to let this plugin control repository deletion as well as repository creation. By default, this feature is disabled and when a repository is deleted in ChiliProject / Redmine, it is not deleted in gitolite. This is a safety feature to prevent the accidental loss of data. If this feature is enabled, the safety is turned off and the repository files will be permanently deleted when the Project/Repository is deleted in ChiliProject/Redmine.

Show Checkout URLs can be disabled to hide the git URL bar in the repository tab. It is enabled by default.

See below in the "Caching" section of this readme for more information on caching and how the caching variables should be configured.

A Note About PATH variables

One major source of issues with this plugin is that Rails needs to be able to run both sudo and git. Specifically, these programs need to be in one of the directories specified by the PATH variable, in your Rails environment. This requirement has been known to cause problems, particularly when installing on FreeBSD.

To address this problem in the Apache + Passenger configuration, one possible solution is to do the following:

(1) Create a new file: /usr/local/bin/ruby18env, with the following code, modifying the PATH shown below to include all relevant directories:

#!/bin/sh
export PATH="/usr/local/lib/ruby/gems/1.8/bin:/sbin:/bin:/usr/sbin:/usr/bin:/usr/local/sbin:/usr/local/bin"
[path_to_your_ruby_executable, e.g. /usr/local/bin/ruby18] $*

(2) Make this file executable:

chmod 755 /usr/local/bin/ruby18env

(3) In your httpd.conf file, replace (or add) your PassengerRuby directive with:

PassengerRuby /usr/local/bin/ruby18env

Note that this may be an issue for configurations other than Apache + Passenger, but as this is one of the most common configurations, instructions for that are provided above.

Thanks to user Tronix117 for helping to track down this issue and provide a solution for Apache + Passenger.

"Smart" HTTP Functionality

Smart HTTP is an efficient way of communicating with the git server over http/https availalbe in git client version 1.6.6 and newer. A more detailed description of what Smart HTTP is all about can be found at: http://progit.org/2010/03/04/smart-http.html

This plugin allows you to automatically enable Smart HTTP access to your repositories. It is highly recommended that you enable Smart HTTP access only via HTTPS -- without encryption this is very insecure. However, you will require a valid SSL certificate for this to work properly, otherwise you will get permission errors. If you want to enable (insecure) access via unencrypted HTTP go to the repository settings tab and select "HTTPS and HTTP" under the "Git Smart HTTP" tab.

Where a password is required, this is your Redmine user password.

Once Smart HTTP is enabled no further configuration is necessary. You will be able to clone from/to the HTTP[S] URL specified in the URL bar in the Project/Repository tab.

Also note that you will need to ensure that Basic Auth headers are being passed properly to Rails for this to work properly. In Apache with mod_fcgid this may mean you need to add "Passheader Authorization" into the virtual host configuration file.

Caching Options

As of version 0.3.0 and later this plugin includes code for caching output of the git command, which is called to display the details of the git repository. Redmine/ChiliProject by default calls git directly every time this information is needed. This can result in relatively long page load times.

This plugin caches the output of git commands to dramatically improve page load times, roughly a 10x speed increase. On a 1GB VM running Ubuntu 11.04 median repository page load times dropped from 2300ms to 180ms. Testing was done with ab utility in the apache2-utils package.

There are three configurable caching parameters in the plugins settings page: Max Cache Elements, Max Cache Element Size and Max Cache Time.

Max Cache Elements is the maximum number of git commands for which to cache the output.

Max Cache Element Size is the maximum size of the git output to cache. Anything above this size won't be cached, and git will be called directly every time this command is run.

Max Cache Time is the maximum amount of time the git command will be cached. No matter what, the output of git commands for a given repository are cleared when new commits are pushed to the server and the post-receive hook is called.

This caching functionality only works in Redmine 1.2.x+ and ChiliProject v2.x+ -- while this plugin is compatible with ChiliProject 1.x the caching functionality is not.

Notification to CIA.vc

As of version 0.4.0, this plugin can notify CIA.vc when changes are pushed to the repository. The project identifier on CIA.vc must match the project identifier specified in ChiliProject/Redmine exactly

Automatic Mirror Updates

As of version 0.4.0, this plugin can automatically push updates to repository mirrors when new changes are pushed to the repository. Mirrors must grant access to the public key defined in the gitolite_admin_id_rsa.pub public key file, which is displayed for convenience in the repository settings tab.

Fast Deployment with YourChili Bash Library

Instead of installing/configuring by hand, one option for quickly deploying a fully-functional system for hosting git repositories on an Ubuntu VPS is the YourChili bash library. (http://github.com/ericpaulbishop/yourchili) This library allows you to quickly deploy ChiliProject, with this plugin to an un-initialized VPS node with Ubuntu 10.10 (from e.g. Linode) using nginx and Passenger. Just run the init_nginx_stack.sh script followed by the chili_test.sh script, modifying the variables in those scripts as desired. This library is still under development, so these instructions may need to be updated in the near future.

Tested Configurations

This plugin has been primarily tested on Ubuntu Server 10.10 and 11.04 (32 and 64 bit) with ChiliProject v1.x, ChiliProject 2.0.0 and Redmine 1.2.1 with PostgreSQL as the database (July, 2011). It is possible that some debugging will be necessary for other configurations.

Required gems

In order to use this plugin you must have the following gems installed:

lockfile

inifile

net-ssh

Copyright & License

This plugin is based largely on the Gitosis plugin by Jan Schulz-Hofen for http://plan.io. Several updates/fixes were provided by github users untoldwind, tingar and ericpaulbishop. These updates were merged together and expanded upon by Eric Bishop to create this more comprehensive Git Hosting plugin.

Copyright (c) 2010-2011 Eric Bishop ([email protected]) MIT License.

Copyright (c) 2009-2010 Jan Schulz-Hofen, ROCKET RENTALS GmbH (http://www.rocket-rentals.de). MIT License.