Gitolite Install – part 3

We've been through what Gitlolite is, and how it sets up between the server and your local client.  The second article covered what ssh is, and how Gitolite handles ssh differently, than a program like Putty.  We now have enough background information to install Gitolite, and know what we're trying to accomplish with each step.

Preliminary Set Up

I assume you have installed Apache, Perl, and Git on your server.  These all can be installed with your package manager.  Let's call the server,  "gitolite_server".  You've installed Git on your local machine.  If your running Windows on your local machine, you probably access Git in the Msysgit BASH shell.

On the server, in addition to your regular user name, login as root and create a "virtual" user, let's call the virtual user "gitadmin."  As the gitadmin virtual user we will install Gitolite in your virtual user home directory, which is different from your regular user "real" account home directory.

Setting up the Ssh

After installing your base components, we want to set up our ssh connections. A key point to remember, ding, ding, ding.  We want to set up two ssh key-pairs on your local machine, one for you as a regular user to login to the gitolite_server together with with passphrase, login, and password.  You can use Putty for this connection if you like.  Change the name of this key-pair to something like: id_rsa_aname and id_rsa_aname.pub.  Note, this connection could be in the Putty dsa format, in which case, you would have and id_dsa and id_dsa.pub.  The second connection has to be SSH2 RSA, or you've got trouble.  I prefer to keep both keys in the RSA format.

The second key-pair is for the "gitadmin" virtual user.  We'll use this for the Gitolite administrator's connection to Gitolite.  Generate the gitadmin key-pair on your local machine in the Git Msysgit BASH window by typing:  "ssh-keygen -t rsa".  Remember, on this key-pair, we do not want a passphrase, at least for the initial install, just hit the return key twice.  Rename this key-pair to something like id_rsa_git and id_rsa_git.pub.  We end up with two key-pairs, if you don't see them look in the ~/.ssh directory on your local machine.

We now copy the public keys to the server, so ssh can find them, to set up your connection.  First, login to the server as the regular real user "aname".  Copy from your local machine to the server, the id_rsa_aname.pub file, and put it in "/home/aname/.ssh".   Now, "su" into the virtual gitadmin user account, and copy the id_rsa_git.pub key to a temp directory you create, something like "/home/gitadmin/temp".  Rename the pub file to something like, "gitadmin.pub".   Do not place this key in your /home/gitadmin/.ssh directory.  Gitolite will use the ~/gitadmin/.ssh directory to create its authorized_keys file from the public key you just copied.

Back to the local machine, the ssh-agent on your local machine loads your ssh private key file, checks for your passphrase, and then generates a signature to pass to the server.  The ssh-agent is loaded by the .bash_profile file on your local machine, when you first open the shell.  Another BIG gotcha is the ssh-agent doesn't know about any of your private keys until you tell it with an "ssh-add".  Both private keys need to be added in the .bash_profile script before everything will work.  Here's a look at my .bash_profile on my local machine.

Starting the ssh-agent in .bash_profile on your local machine

After updating your .bash_profile, close and re-open your local shell to initiate the changes.

We're almost there.  The last thing we need to do with ssh is to tell the ssh-agent which private file to use when opening a particular connection.  This is done in a file called "config" with no extension placed in your .ssh directory.  You'll have to create this file from scratch.  It looks something like this:

Telling the ssh-agent which key to use in ~/.ssh/config

 

 

Gitolite - Getting the Software Installed on the Server

OK, we've set up our ssh connection, let's start setting up Gitolite.  On the gitolite_server, as user "gitadmin", its time to download the Gitolite software.  This comes from GitHub, in your gitadmin home directory, type:

git clone git://github.com/sitaramc/gitolite.git

And the Gitolite software will be loaded on your server.  Isn't Git wonderful.  You'll find a Gitolite directory among other directories.

This is just the software, it still needs to be built, but first, as the virtual user "gitadmin" on the server, check your path environmental variable, "echo $PATH" to make sure ~/gitadmin/bin, or $HOME/bin,  is in your path.  This puts all the Gitolite scripts in your path.  If $PATH/bin is not set,  amend $PATH to add it in your .bash_profile or .bashrc file.  It should be there.

What we have now is a bunch of installation files; we need to install Gitolite on the server.  Let's do the build, still as user "gitadmin" on the server, type:

cd gitolite

./src/gl-system-install

This installs Gitolite, the program, on the gitolite_server.  Note, if you update Gitolite in the future just pull from GitHub, and run system install again, and you're all set.

Next, we want to create a "bare" gitolite-admin repository on the server, and designate user "gitadmin" as the Gitolite administrator by telling Gitolite to use the gitadmin public key.   Since we hooked up our path earlier, do this from the $HOME directory.  To create our gitolite-admin repository, type:

cd ~
gl-setup ~/temp/gitadmin.pub

All Gitolite commands start with gl-  and can be found in ~/gitolite/src.   After setup, you now have in your ~/repositories directory a gitolite-admin.git bare repository, and a testing.git bare repository, you can use the testing repository to check the communication back and forth between your local machine and the server.  All repositories on the server should be bare repositories, and are default located in ~/repositories.  Repositories on the server usually have the .git extension.  You can store your central repositories anywhere on the server, but I found the default ~/repositories works fine, and I don't have to set the path to the new repository directory in my .gitolite.rc file.

Now, we test our connection from our local machine.  If you don't get an output like shown below, you're ssh connection is not set up correctly, and you should not  install Gitolite on your local machine until the ssh connection is correct.

On your local machine in the Git shell, type "ssh gitadmin@gitolite_server info".   Your output should look something like shown in the next image.   Some of the text in this image has been blacked out for confidentiality.

What a good ssh connection looks like

 

Setting up your local gitolite-admin repository

In order to talk to the bare repository on the server, we need to do "git push" and "git pull" commands from a gitolite-admin regular repository on your local machine.  Next we'll install the gitolite_admin local repository on your local machine.  Will do this with a git clone.  Back on your local machine in your home directory, type:

git clone gitadmin@gitolite_server:gitolite-admin

Congratulations.  Your done the install.  You now should have a full fledged gitolite-admin repository on your local machine at ~/gitolite-admin.

To change permissions on what repositories and what users can access those repositories on the gitolite_server, you make changes on your local machine in the gitolite-admin repository, commit those changes, and then "git push" them to the server.  Use the testing repository to play around, make changes and verify to yourself that everything is working properly.

Be aware, that you, as gitolite administrator, because you set up all your paths, urls, and keys, access repositories slightly differently than a regular user.  You use something like: gitolite_server:testing  to address a repository.  The regular users use something like dbowe@gitolite_server:testing.git.  Here's a look at the administrator's url in the .git/config file.

What the administrator's URL looks like in .git/config

 

That's about it, read the documentation on how to grant authorizations.  That part of the documentation is pretty good.  Speaking of clear documentation, after I got everything installed properly, the documentation made sense, before that it was all Greek.

Next we'll talk about troubleshooting when something's not right.

Comments

Gitolite Install – part 3 — 2 Comments

  1. I’m not sure why you add the gitolite admin key to the .bash_profile. What’s the point of the gitolite private key being loaded by ssh-agent? I don’t think it’s necessary, but I probably missed something.

    I finally have it working (and probably never would have without your article, thank you very much) and I’m using the same user “gitolite” for both of my repositories in “~/.ssh/config” – just switching the key and using a different host to be able to differentiate them on the command line, like so:

    host gitadmin user gitolite hostname turin.webhop.net port 443 IdentityFile ~/.ssh/gitolite
    host myrepo user gitolite hostname turin.webhop.net port 443 IdentityFile ~/.ssh/mike

    so the following works because of the way the conf/gitolite.conf file is configured:
    git clone gitadmin:gitolite-admin

    or in some other folder:
    git clone myrepo:dev