Setting up GitLabHQ on RHEL5

(Note: commenting on this site has been disabled. If you enjoy the article or have any questions, come find me on twitter.)

On October 13th, GitLabHQ launched.

As anyone who has spent much time with RHEL5 knows, they have a decided emphasis on stability and rarely are the latest and greatest versions of software or libraries available through the standard RPM repositories. This means that trying to run cutting edge software, such as GitLabHQ, will require a bit of effort to get versions of the libraries and dependencies that are new enough to support it.

What follows are the hoops I had to go through in order to get GitLabHQ running on my RHEL5 server. Your milage may vary.

All of the following instructions are written as though you are running as the root user (to keep the command prompts below cleaner looking). If you are not the root user, be sure to use “sudo” as appropriate for your environment.

Installing Ruby, Gems, and Rails

As with most every other library needed to run GitLabHQ, the Ruby available in the RHEL5 rpm repos is nowhere near new enough.  Personally, in this RPM-driven environment, I do everything I can to avoid installing applications from source. Lucky for me that imeyer has rolled out an RHEL-compatible RPM spec file for Ruby 1.9.2 on (where else) GitHub (https://github.com/imeyer/ruby-1.9.2-rpm/tree/e3609d8c786fcf5a57aa2a7d35d898c7d59c6826)

With a few alterations, his instructions worked well (though I had to ‘yum install’ a handful of dependencies):

1. The spec file has been updated to use ruby 1.9.2-p290 but his instructions still reference p180, so adjust accordingly
2. The RPM file will be generated for your architecture, so it may not be the i386 build that he references in his instructions

The distribution comes with rubygems, so it’s not necessary to install it separately, though it may be worth updating it after installing the ruby 1.9.2 rpm:

$ gem update --system

With ruby installed and RubyGems up-to-date, installing rails and passenger is easy:

$ gem install rails --include-dependencies --no-rdoc --no-ri
$ gem install passenger

Since I use Apache2 as my back-end web server (i.e. behind my Varnish3 wall), it was necessary to install passenger’s mod_rails module.  Fortunately, passenger has a script that will build it for you and then show you how to install and enable it for your various vhosts. Simply run the following command and follow the on-screen instructions:

$ passenger-install-apache2-module

 

Installing and Configuring Gitosis

In case you aren’t already familiar with it, Gitosis is a brilliant little tool that allows you to provide SSH-key based git commit access to multiple developers without having to maintain individual user accounts for each on your server. Instead, it uses a dedicated gitosis user (so you only have to configure server permissions for one user) and that user interacts with the git repositories on behalf of the developers.

The official Gitosis installation instructions can be found here: http://eagain.net/gitweb/?p=gitosis.git;a=blob;f=README.rst;hb=master

For me, things were very simple:

$ yum install gitosis

Once you have gitosis installed, create a gitosis user (we’ll use “git” as the user name) and an SSH key for it (saving it to the new user’s home):

Note that you can increase security by using a different user account as the gitosis-admin from the one who manages the repositories, but for the sake of simplicity I’m combining the two in this tutorial.

$ adduser -r -m --shell /bin/sh --comment 'git version control' git
$ mkdir /home/git/.ssh
$ chown git:git /home/git/.ssh 
$ ssh-keygen -t rsa
Generating public/private rsa key pair.
Enter file in which to save the key (~/.ssh/id_rsa): /home/git/.ssh/id_rsa

If the key fingerprint looks like this:

01:23:45:67:89:0a:bc:de:f0:12:34:56:78:90:ab:cd user@server.com

You will have to manually edit the id_rsa.pub file to remove the @ (it, along with other symbols, offends gitosis, and you will get an error on the next step)

$ nano /home/git/.ssh/id_rsa.pub

Finally, initialize gitosis and activate the post-update hook (note: you are using the sudo command to run the gitosis-init command as the new git user):

$ sudo -H -u git gitosis-init < /home/git/.ssh/id_rsa.pub
$ chmod 755 /home/git/repositories/gitosis-admin.git/hooks/post-update

Voila

Installing Python Pip

RHEL5 ships with python but does not come with pip (which stands for Pip Installs Python — nerd recursion).

At first, I tried installing it via yum, but that didn’t seem to do the trick, so I broke my RPM rule and went rogue following these instructions: http://www.pip-installer.org/en/latest/installing.html

For me, the following two commands worked beautifully:

$ curl http://python-distribute.org/distribute_setup.py | python
$ curl https://raw.github.com/pypa/pip/master/contrib/get-pip.py | python

SQLite 3.6

As is now the theme of this post, RHEL5 ships with an outdated version of SQLite3.  In order to bring it up to the standards required by GitLabHQ, we have to grab two updated RPMs off of pkgs.org:

Make sure that you get the correct RPM for your architecture. In my case, my servers are running on x86_64:

$ rpm -Uvh http://dl.atrpms.net/el5-x86_64/atrpms/testing/sqlite-3.6.20-1.el5.x86_64.rpm
$ rpm -Uvh http://dl.atrpms.net/el5-x86_64/atrpms/testing/sqlite-devel-3.6.20-1.el5.x86_64.rpm

And now the main event! GitLabHQ!

Dependencies out of the way, it’s time to get down to installing and configuring the beast following the instructions here: https://github.com/gitlabhq/gitlabhq/wiki/Install

$ git clone git://github.com/gitlabhq/gitlabhq.git
$ cd gitlabhq/
$ pip install pygments
$ gem install bundler
$ bundle

I had a minor hiccup with bundle as it had difficulty installing nokogiri.  Following the instructions on http://nokogiri.org/tutorials/installing_nokogiri.html worked for me, though:

$ yum install -y libxml2 libxml2-devel libxslt libxslt-devel
$ gem install nokogiri
$ bundle

The rest of the bundle process went smoothly.

Next up is to initialize the database for GitLabHQ.  In my case, when running the ‘rake db:setup’ command, I encountered this:

$ RAILS_ENV=production rake db:setup
(in /var/dev/gitlabhq)
rake aborted!

uninitialized constant Rake::DSL
/usr/lib64/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/tasklib.rb:8:in `<class:TaskLib>'
/usr/lib64/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/tasklib.rb:6:in `<module:Rake>'
/usr/lib64/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/tasklib.rb:3:in `<top (required)>'
/usr/lib64/ruby/gems/1.9.1/gems/rake-0.9.2/lib/rake/testtask.rb:4:in `<top (required)>'
/usr/lib64/ruby/gems/1.9.1/gems/railties-3.1.0/lib/rails/test_unit/testing.rake:2:in `<top (required)>'
/usr/lib64/ruby/gems/1.9.1/gems/railties-3.1.0/lib/rails/test_unit/railtie.rb:12:in `block in <class:TestUnitRailtie>'
/usr/lib64/ruby/gems/1.9.1/gems/railties-3.1.0/lib/rails/railtie.rb:183:in `call'
/usr/lib64/ruby/gems/1.9.1/gems/railties-3.1.0/lib/rails/railtie.rb:183:in `block in load_tasks'
/usr/lib64/ruby/gems/1.9.1/gems/railties-3.1.0/lib/rails/railtie.rb:183:in `each'
/usr/lib64/ruby/gems/1.9.1/gems/railties-3.1.0/lib/rails/railtie.rb:183:in `load_tasks'
/usr/lib64/ruby/gems/1.9.1/gems/railties-3.1.0/lib/rails/engine.rb:395:in `block in load_tasks'
/usr/lib64/ruby/gems/1.9.1/gems/railties-3.1.0/lib/rails/application/railties.rb:8:in `each'
/usr/lib64/ruby/gems/1.9.1/gems/railties-3.1.0/lib/rails/application/railties.rb:8:in `all'
/usr/lib64/ruby/gems/1.9.1/gems/railties-3.1.0/lib/rails/engine.rb:395:in `load_tasks'
/usr/lib64/ruby/gems/1.9.1/gems/railties-3.1.0/lib/rails/application.rb:99:in `load_tasks'
/usr/lib64/ruby/gems/1.9.1/gems/railties-3.1.0/lib/rails/railtie/configurable.rb:30:in `method_missing'/var/dev/gitlabhq/Rakefile:7:in `<top (required)>'
/usr/lib64/ruby/1.9.1/rake.rb:2373:in `load'/usr/lib64/ruby/1.9.1/rake.rb:2373:in `raw_load_rakefile'
/usr/lib64/ruby/1.9.1/rake.rb:2007:in `block in load_rakefile'/usr/lib64/ruby/1.9.1/rake.rb:2058:in `standard_exception_handling'
/usr/lib64/ruby/1.9.1/rake.rb:2006:in `load_rakefile'/usr/lib64/ruby/1.9.1/rake.rb:1991:in `run'
/usr/bin/rake:31:in `<main>'

If you see that, it means that your version of rake is probably out of date.  An easy way to check is:

$ rake --version
rake, version 0.8.7

If yours is 0.8.7, you will need to update it. Run the following command to update rake:

$ gem install rake

Now, unfortunately, since you installed your bundle using the older version of rake, you will encounter issues later on (see the Post-Install Issues section below for details).  This means that it’s necessary to update your bundle dependencies:

$ bundle update

With those adjustments in place, the rest of the steps went off without a hitch:

$ RAILS_ENV=production rake db:setup
$ RAILS_ENV=production rake db:seed_fu

The last steps are to edit config/gitosis.yml and then add a virtual host to your apache install and restart apache. It is important to note that you need to set the document root to /path/to/gitlabhq/public, and not just /path/to/gitlabhq

You will now be able to access your own GitLabHQ in your browser using the default administrator account:

user: admin@local.host
pass: 5iveL!fe

Enjoy!

Post-Install Issues (and Resolutions)

Unable to connect to gitosis

If you have made multiple attempts to run the gitlabhq rails application, and now you find you can’t create projects (you get the Gitosis Error page), have a look in your /tmp folder.  If you see a gitlabhq-gitosis.lock file, make sure it’s owned by the same user that owns /path/to/gitlabhq/config/environment.rb (i.e. the user that the ruby application is running as):

 -rw-r--r-- 1 git    git           0 Oct 20 15:36 gitlabhq-gitosis.lock

(Many thanks to infomaniac50 for this fix: https://github.com/gitlabhq/gitlabhq/issues/41)

The Passenger Error Screen

If you get through everything and see this error in your browser:

git://github.com/gitlabhq/grit.git (at master) is not checked out. Please run `bundle install` (Bundler::GitError)

Make sure that your version of rake is updated to 0.9.2 (at the time of this writing) and that you remembered to update the bundle dependencies (from inside /path/to/gitlabhq):

$ gem install rake
$ bundle update