Gitolite is an amazingly simple, self-hosting, git server, but it's not always easy to install.

Well I say that, but what I really mean to say is that the installation instructions on their site expect you to know a few things about *nix administration. It's easy enough to install, as their instructions state:

"If your Unix-fu and ssh-fu are good"

If you're not an every day linux user or a linux admin there are some implied steps that you're not going to know without doing some searching.

This article will hopefully be your replacement for those searches.

My Linux Setup

For this article I will be using a minimal install version CentOS 7, but these steps will work on most linux distros and FreeBSD. I've tested it on CentOS7 and Ubuntu 14.04.

My setup has the following packages installed:

epel-release (the repository for the latest Extra Packages for Enterprise Linux)

If you'd like to setup a minimal install of CentOS 7 in VirtualBox on your own machine you can take a look at the following article for step-by-step instructions: Install CentOS 7 Minimal in VirtualBox

The Rundown

The rest of this article will provide step-by-step instructions for installing Gitolite on your machine.

For most of the steps you will need root privileges to install the necessary packages or run the necessary commands. I recommend using sudo or your OS's equivalent rather than using the root account.

Step 1 - Update

The first step to take, and this usually goes for any project you're working on, is to make sure the OS has the most up-to-date packages. Let's go ahead and run update.

[jeramy@localhost ~]$ sudo yum -y update

I had roughly 68 out-of-date packages that needed to be updated when running yum -y update. That's not a bad amount of updates and the process only took a couple of minutes.

Step 2 - Add git user

Step 3 - Install dependencies

If you haven't installed autoconf or git yet, go ahead and do so now. Those are the only two packages, missing from the minimal CentOS 7 install, actually required for Gitolite to work. There are a few dependencies that you'll see being installed, but all-in-all the install should only take roughly 45 seconds.

[jeramy@localhost ~]$ sudo yum -y install autoconf git

Step 4 - Get Gitolite

Now that our OS is up-to-date and has the necessary dependencies for Gitolite to operate let's go ahead and clone the gitolite repository from Github. We'll need to do this as the git user. We'll also need to make a bin directory in our $HOME directory so that we can create a symbolic link to gitolite after it's installed. Please take note that when we switch to the git user we need to change the working directory to the git user's home directory.

[jeramy@localhost ~]$ su - git
[git@localhost ~]$ cd ~

Next we make the ~/bin directory. Please take note of the ~ character when creating the directory. We use the ~ character here just in case we forgot to change directories into the git user's home directory.

[git@localhost ~]$ mkdir ~/bin

Now let's clone Gitolite's github repo.

[git@localhost ~]$ git clone git://github.com/sitaramc/gitolite

Step 5 - Install Gitolite

This next operation didn't necessarily have to be separated into it's own step, but the title of my last step was Get Git, so it didn't really fit there. Installing Gitolite with this next commmand creates a symbolic link in our ~/bin folder.

For the install to work, we must be in the $Home directory of the git user and you must use the full path of the ~bin directory which in this case is just ~/bin. Using /bin or bin will NOT work.

[git@localhost ~]$ gitolite/install -ln ~/bin

That was pretty anti-climatic. You may or may not have noticed that we didn't get a confirmation or anything that the install was successful. Let's check our ~/bin directory now to see if the symbolic link was created.

[git@localhost ~]$ ls ~/bin

You should now see the link to gitolite in your ~/bin directory

Step 6 - SSH Key Generation

Gitolite is now installed on our machine, but we aren't quite finished yet. We now have to setup Gitolite, and to do that we need an ssh key from an account other than the one we used to install it (our git user).

Let's create and send an ssh key from our local box and send it to our server.

On your local machine, or on an account other than git, create a new ssh key now (if you have one already skip this part).

Linux, FreeBSD, Mac OS X, and Windows users that have msysgit:

In your terminal

[jeramy@localhost ~]$ ssh-keygen

You'll notice that two keys have been generated for us. A public and private key. The public key is yours to share freely among sites that you will want to securely communicate with. The private key however, should be kept safe and sound in your .ssh directory and should never be shared.

Servers will encrypt data using their own private key and your public key and you will be able to unencrypt data using your private key and their public key, and vice versa. This keeps your data safe from man-in-the-middle attacks. A sniffer would have to know the private keys on both endpoints of the data flow in order to unencrypt any of the data they intercepted. They can have both public keys and never be able to unencrypt your data without those private keys.

Windows Users without msysgit:

Other Windows users will need to download PuTTY and follow the link below for directions to create a local ssh-key. Also it wouldn't hurt for Windows users to use WinSCP to transfer their public ssh key to the server.

Step 7 - Transferring our Public Key

Transferring our public key (notice I said public key) is by far the hardest part of getting Gitolite setup.

Now that our ssh keys have been generated we need to transfer the public key to our git user.

Linux, FreeBSD, Mac OS X, and Windows users that have msysgit:

In your terminal

First, from your $HOME directory, make a copy of your public ssh key (replace jeramy with the name of the account you are currently on):

[jeramy@localhost ~]$ cp .ssh/id_rsa.pub jeramy.pub

If you ssh in on the regular ssh port (22):

[jeramy@localhost ~]$ scp jeramy.pub git@localhost:/home/git

If you ssh in on a port other than 22 like 2222:

[jeramy@localhost ~]$ scp -P 2222 jeramy.pub git@localhost:/home/git

You will be prompted to input the git user's password and to add the git server to your list of known hosts. You'll want to input the password and select yes when that happens.

If the transfer was successful your git user's home directory should now contain your public key.

Windows Users without msysgit:

Non-msysgit windows users will need to use WinSCP to transfer their public key over.

Step 8 - Refresh Bash and Finish Setup

We are almost done. The only steps left are to refresh the git user's .bash_profile and the final Gitolite setup command.

From the git user's home directory, as the git user, go ahead and refresh the .bash_profile now (Ubuntu users will need to refresh .profile instead.).

[git@localhost ~]$ source .bash_profile

You won't get any response back if the refresh was successful.

The final thing to do is setup Gitolite with our recently created ssh key.

[git@localhost ~]$ gitolite setup -pk jeramy.pub

If you receive an error saying that the "gitolite" command cannot be found, make sure you refreshed your .bash_profile with source .bash_profile. This will add the symbolic link to gitolite, found in your ~/bin directory, to your path.

If all was successful you should see a couple of messages stating the initialization of empty Git repos, and maybe a couple of warnings about missing .ssh files. Don't worry, this is normal.

Step 9 - Testing

Like any good developer or sysadmin we always want to test our work when it's done. Let's go ahead and do that now.

From within the account you created your public key, clone the gitolite-admin repository from your new Gitolite server.

[jeramy@localhost ~]$ git clone git@localhost:gitolite-admin

Your home directory should now contain the gitolite-admin folder and all its contents.

Wrapping up

We now have a working remote git server (or local if that's what you're using it for). The setup really wasn't that hard at all, but we did fill in a few gaps left by the installation instructions on Gitolite.com.

I won't be going in to how to use Gitolite because there are a lot of great tutorials out there on how to use it. However, sometime in the near future I will be releasing a hobby project, using Elixir and the Phoenix Framework, that works with Gitolite, called Firebird.

Well, that's it for this article. Hopefully this helps out a few people that have been trying to get Gitolite installed.