I really enjoy github. It’s quite exceptional for both project status tracking and code accessibility. Unfortunately the github private pricing is a bit steep when all you really want to do is leverage their tools on some personal projects, without making them public to the world. (not that I’m advocating you not give them money. you really should. seriously, they are awesome.)

However, if you are like me and want to have a private project management interface that is integrated with git (and you don’t mind running your own server). Then you should definitely check out the GitLabHQ project.

The quick and dirty summary is that it lets you setup a private github-like service on your own server, giving you most of the major features without breaking the bank and exposing your (likely terrible) code to prying eyes.

That being said, the one thing the project doesn’t currently do well is give a complete tutorial that will get you setup. In my efforts I attempted to follow the Installing GitLabHQ on Ubuntu Server 10.04 LTS guide on the project’s github wiki page, but found it outdated and, in parts, misleading. So what I’ve assembled here is the complete step-by-step guide I used to go from start to finish.

---

I had a number of restraints on the install I was doing that should be noted

1. The platform I performed this install on was Ubuntu Server 10.04 64bit, but other linux platforms should be able to perform equally as well provided the same access to the packages needed
2. I wanted to set it up using a non-standard SSH port (this is something not covered in any of the tutorials I ran across)
3. I was starting from a nearly fresh install. A clean slate isn’t necessarily important but if you are installing on a server that has older versions of things (such as Ruby) then you’ll need to do upgrades that aren’t covered here
4. I wanted to setup the stable 1.2 Pronto branch of GitLabHQ. The only tricky part here is the use of gitosis over gitolite. Development on the gitosis project has apparently stopped and gitolite is now taking over its place. The Pronto branch of GitLabHQ uses gitosis, while the current master branch (v2.0) uses gitolite. It isn’t entirely clear from the documentation what you need, so I’m clarifying, we are using gitosis

---

Download the latest server updates
This is always a good step to start with just to save yourself any potential pain down the road

sudo apt-get update
sudo apt-get dist-upgrade -y

Create a gitlabhq user account
This will be the user that runs GitLabHQ. The setup will prompt you for a password and then setup their home directory. It’s important to note that I deviated from the main GitLabHQ tutorial here and made this an actual, rather than system, user. You’ll be doing a bit of work from this user’s shell, so having auto-complete, bash history, and other user-friendly features was nice to have.

sudo adduser gitlabhq

Add gitlabhq to the admin group so it can sudo
I didn’t particularly like having to do this step, but there are a few steps later involved with setting up gitosis that need sudo privileges. If you prefer to use an actual admin user to do the sudo portions you can, but this guide assumes the gitlabhq user has been granted sudo (which you can remove once everything is setup)

sudo adduser gitlabhq admin

Download prerequisite packages including postfix for sending email
This set of packages includes gitosis

sudo aptitude install git-core curl gcc libxml2-dev libxslt-dev sqlite3 libsqlite3-dev libcurl4-openssl-dev libreadline5-dev libc6-dev libssl-dev libmysql++-dev make build-essential zlib1g-dev python-dev python-setuptools postfix gitosis -y

Download tar of ruby 1.9.2
The default Ubuntu package repositories currently (12/15/2011) only have Ruby 1.9.1, so we’ll install 1.9.2 manually

wget http://ftp.ruby-lang.org/pub/ruby/1.9/ruby-1.9.2-p290.tar.gz

Extract Ruby tar

tar -xzvf ruby-1.9.2-p290.tar.gz

Configure, make, and install

cd ruby-1.9.2-p290
./configure
make
sudo make install

Verify Ruby installed correctly

cd ~
ruby --version

Update the Ruby Gems to the latest version

sudo gem update --system

Configure gem not to install rdoc or ri

echo "gem: --no-rdoc --no-ri" > ~/.gemrc

Now add a dedicated git user for Gitosis interaction
This will add our dedicated gitosis user and place their home at /home/git. This is where all your repositories will live. This setup is different from most of the gitosis setups which place the repositories in /srv/gitosis, but as we are serving up gitosis access through GitLabHQ, we can have them in user space.

sudo adduser --system --shell /bin/sh --gecos 'git version control' --group --disabled-password --home /home/git git

Add the gitlabhq user to the new git group
Add the gitlabhq user to the git group so they have access to the repositories

sudo usermod -a -G git gitlabhq

Create ssh key
When prompted for the file in which to save the file, press Enter. When prompted for a passphrase, press Enter. When prompted to confirm the passphrase again, press Enter.

ssh-keygen -t rsa

Now run the gitosis-init command as the newly created git user account and give it the gitlabhq users public key we just created. This will allow the gitlabhq user to admin our gitosis install.

sudo -H -u git gitosis-init < ~/.ssh/id_rsa.pub

Copy the SSH public key for the gitlabhq user to the git user account

sudo cp /home/gitlabhq/.ssh/id_rsa.pub /home/git/.ssh/id_rsa.pub

We need to change the permissions on the gitosis admin repo hook

sudo chmod 755 /home/git/repositories/gitosis-admin.git/hooks/post-update

Install Rails framework

sudo gem install rails

Download the GitLabHQ 1.2 release
Note this differs significantly from the official guide. What isn’t mentioned in the official guide is that if you get GitLabHQ straight from the git repository, you are retrieving the master branch, which is already setup to use gitolite as the repository management system. What also is not entirely clear is the upgrade path from Pronto (1.2) to the Master (2.0), including the migration to gitolite. So you have to make a decision; if you setup the static 1.2 snapshot, the updating process is likely manual, but if you go with 2.0 you’ll have to deviate from this guide and figure out the upgrade path on your own.

cd ~
wget https://github.com/gitlabhq/gitlabhq/tarball/v1.2.2
tar -xzvf v1.2.2
mv gitlabhq-gitlabhq-4deac4c gitlabhq
cd gitlabhq/

Open the Rakefile to edit

nano Rakefile

To prevent the Rake::DSL error, add the following two lines right after the last comment. Use Control + O, then Ctrl + X to save and exit

require 'rake/dsl_definition'
require 'rake'

Install gitlabhq dependencies
I personally ran into some issues performing the bundle install step. If it does complain about being unable to install any of the gems, try installing them by themselves before running the “sudo bundle install” command again. (Yeah not a particularly helpful hint, but I lost the history that told me exactly what gem I had issues with as the gitlabhq user wasn’t setup as a normal user at the time)

sudo easy_install pygments
sudo gem install bundler
sudo bundle install

The next two steps are only applicable if you run SSH on a non-standard port

Setup SSH config file
The gitlabhq user needs to be able to use SSH as part of it’s operation. This creates a problem if you run SSH on a non-standard port as there doesn’t seem to be a gitlabhq config setting for this (at least not that I found). So a really easy work around is to set the Port option in the gitlabhq user’s ~/.ssh/config file. So for instance, if you run ssh on 2222, add this to the config file:

Port 2222

This will cause all SSH commands to default to port 2222 for the user without setting the option globally.

Modify the GitLabHQ gitosis configuration
Another place you’ll likely need to change the SSH port is in the ~/gitlabhq/config/gitlab.yml file. So the gitosis portion of the file should look something like this (assuming port 2222 for SSH again):

# Gitosis congiguration
gitosis:
  admin_uri: git@localhost:gitosis-admin.git
  base_path: /home/git/repositories/
  host: localhost
  git_user: git
  port: 2222

Modify the GitLabHQ gitosis configuration
Now we need to accept the SSH host fingerprint manually. So SSH to your localhost and accept the fingerprint. When prompted authenticate the RSA key fingerprint, type yes.

ssh localhost
exit

Setup the gitlabhq database

bundle exec rake db:setup RAILS_ENV=production

Next seed the database with the initial data needed

bundle exec rake db:seed_fu RAILS_ENV=production

Start the server using WEBrick

rails s -e production

Verify that the server is up and running now by connecting using your web browser

• http://localhost:3000/

Default login credentials

• Login Email: admin@local.host
• Login Password: 5iveL!fe

Congrats! You should now be up and running and able to login to your own private instance of GitLabHQ. If you can’t get to the login page, make sure you don’t have any firewall issues that are blocking port 3000.

Hopefully this guide gave you that little bit of extra detail needed to get up and running.