Three months ago, I tried to start a series about my efforts to find a continuous integration solution that I could get on board with. Things have been pretty crazy (more on that someday) since and I haven’t had much time to work on this entry.
What You Should Have At The End Of This Post
By the end of this post, if you’ve followed the steps correctly, you should be able to add new repositories, configure access and add users to a central/shared git server from the comfort of your Windows environment. I’ve tried to provide enough narrative to explain what you’re actually doing, but this is a very long post; I won’t be offended if you just skip to the good parts.
Prerequisites
You need to have msysgit (or alternative) on your machine. You should already have a ssh key pair installed. You need to be comfortable with git and a bash console. If you’re completely new to Linux, stop reading this and look for some good Linux introductions.
Why I Think Gitosis Is Great
Gitosis is like magic. I think that in order to understand why gitosis is magic, you have to understand a little bit about what life would be like using git without gitosis. As I mentioned in my previous post, the trouble with a git server in a Windows domain is that git-daemon won’t run on Windows. Hosting it on Linux isn’t a simple solution because unless you want the headache of joining the Linux server to your domain, none of your developers will have rights to the machine. In order to provide them with access, you have to manage ssh and keys and folder permissions and… it boils down to a lot of busy work. I hate busywork.
Enter gitosis! Gitosis provides you with a simple way to manage keys, permissions, repositories, web browsing of the repositories and public read-only access. Enough blabbering… it’s time to dive in.
The Environment
For this blog post I’ve created a brand-new VM on version 5.03 of Debian, and version 7.01 of VMWare Workstation. For testing I will use msysgit 1.6.5 on Windows 7. Because I have never been able to get the host OS to communicate with the guest OS by name, I have put an entry in my hosts file on Windows so that I can issue commands to the virtual git server by name rather than IP address. (you can find your hosts file in c:\windows\system32\drivers\etc\hosts)
For the rest of the article, if I say host OS I mean my Windows 7 box running msysgit. If I say guest OS or git server, I’m talking about the Debian VM. Anywhere you see [git-server] just replace it with your git server’s name. Anyplace you see [your@email.com], you should replace it with the email address that you associated with your ssh key.
Installing
Mount the disc to the VM that you installed Debian with. Apt-get will almost always require you to do that.
You need Apache server if you’re going to use gitweb. If it’s not installed this command will handle that:
sudo apt-get install apache2
From the command prompt, type:
sudo apt-get install git-core gitweb git-daemon-run gitosis
This command line is installs 4 packages (and any missing dependencies) for you: git, gitweb, git-daemon and gitosis.
Create A User That “Owns” The Repositories
sudo adduser \
--system \
--shell /bin/sh \
--gecos 'git version control' \
--group \
--disabled-password \
--home /home/git \
git
This command line create the user git and sets their home directory to /home/git. This is where gitosis will keep all the managed repositories.
Update Git-Daemon Configuration
The git-daemon needs to be told where we’re going to be keeping the repositories that it will manage because we’re not using the default location it expects (which was /var/cache/git).
sudo vi /etc/service/git-daemon/run
comment out the last line in the file and replace it with:
exec git-daemon --verbose --base-path=/home/git/repositories/ --export-all
Now issue the command:
sudo /usr/bin/git-daemon restart
If this command results in the error:
fatal: unable to allocate any listen sockets on host (null) port 9418
then there’s a good chance git-daemon is already running in the background. My advice is to run ps –A to find the git-daemon process id and issue a kill command. That will cause git-daemon to re-load your changed configuration.
At this point, the git-daemon should provide public, read-only access. Let’s test that on the host OS:
git clone git://[git-server]/gitosis-admin.git
You should see the following response:
Initialized empty Git repository in [path]
remote: Counting objects: 5, done.
remote: Compressing objects: 100% (5/5), done.
remote Total 5 (delta 0), reused 5 (delta 0)
Receiving objects: 100% (5/5), done.
Create The First Gitosis Admin
You need a way to authenticate with gitosis so that you can manage it remotely via it’s gitosis-admin repository. The way you do this is by providing the public key of your ssh key pair to gitosis.
This may sound intimidating but you can do it very simply by following one of two methods:
Using Only The Bash Prompt:
1. On your host OS, locate the .ssh folder contained in your home directory
2. Open the id_rsa.pub file contained in that directory in a text editor
3. Copy all the text
4. On your guest OS, navigate to /tmp by typing cd /tmp at the prompt
5. Type ‘echo’, then in the console menu under Edit choose paste, then finish the command by typing > id_pub.rsa
Using Vi:
1. On the host, locate the .ssh folder contained in your home directory
2. Open the id_rsa.pub file contained in that directory in a text editor
3. Copy all the contents
4. On your guest OS, type vi id_pub.rsa
5. Hit the ‘i’ key and using the console menu, under Edit, choose the paste option
6. Hit escape, hit ‘:’ then type wq and press enter
Initialize Gitosis
Now that we’ve created the public key for the gitosis admin on the git server, we can initialize gitosis with that key.
sudo –H –u git gitosis-init < /tmp/id_rsa.pub
This invokes the command under the git account you created previously and initializes gitosis with your public key so that you’ll be able to authenticate for push and pull operations with the git server.
Testing Gitosis
Believe it or not, we’re actually ready to check and see whether or not gitosis is ready to go. In your git-bash shell on the host OS, navigate to a directory where you keep your git repositories and enter the following:
git clone git@[git-server-name]:gitosis-admin.git
My command looked like this:
git clone git@[git-server]:gitosis-admin.git
This should pull down the gitosis-admin repository which you can use to remotely manage gitosis.
Setting Up GitWeb
For me, this part was the most difficult, it took me a while to figure out all the steps but it’s definitely worth it.
We need to add www-data to the git group so that it will have read permissions to the repositories.
sudo usermod -G www-data,git www-data
Next we need to provide a way to host gitweb in apache. I’ve seen a few different approaches but prefer the way I’m about to show you.
sudo mkdir /var/www/git
sudo chmod 755 /www/git
sudo cp /usr/share/gitweb/* /var/www/git
sudo cp /usr/lib/cgi-bin/gitweb.cgi /var/www/git
Those four lines are creating a virtual directory in apache for gitweb, copying the gitweb.cgi, css, image and icon files over and setting the proper permissions. Next we need to create a configuration block for our gitweb in apache.
vi /etc/apache2/conf.d
<Directory /var/www/git>
Allow from all
AllowOverride all
Order allow,deny
Options ExecCGI
<Files gitweb.cgi>
SetHandler cgi-script
</Files>
</Directory>
DirectoryIndex gitweb.cgi
SetEnv GITWEB_CONFIG /etc/gitweb.conf
The last file we need to change is the configuration for gitweb itself. Change it to look like the following:
vi /etc/gitweb.conf
# path to git projects (<project>.git)
#projectroot = "/home/git/repositories";
# directory to use for temp files
$git_temp = "/tmp";
#target of the home link on top of all pages
#$home_link = $my_uri || "/";
$ html text to include at home page
$home_text = "indextext.html";
# file with project list; by default, simply scan the projectroot dir.
$projects_list = $projectroot;
# stylesheet to use
$stylesheet = "/git/gitweb.css";
# logo to use
$logo = "/git/git-logo.png";
# the 'favicon'
$favicon = "/git/git-favicon.png";
Now reset apache to reload the new configuration:
sudo /etc/init.d/apache2 restart
Configuring Gitosis
Let’s take a look at the default gitosis configuration file:
[gitosis]
[group gitosis-admin]
writable = gitosis-admin
members = [your@email.com]
Not much there to see, right? Let’s say we want git-daemon to export the repositories so that they can be served to the public as read-only and we also want gitweb to export our repositories for web-browsing. To do that we’d change the config to look like this:
[gitosis]
gitweb = yes
daemon = yes
[group gitosis-admin]
writable = gitosis-admin
members = [your@email.com]
That’s great, but we don’t have any repositories to test this out on (the gitosis-admin repository is special and won’t share out to gitweb). Let’s make a very simple repository to test.
1. On your guest OS make a new directory called test
2. CD to test and type the following commands:
git init
echo This is a test file! > readme.txt
git add .
git commit -m "Adding a readme.txt file"
Let’s add the new repository to gitosis.conf file and create a developer group:
[gitosis]
gitweb = yes
daemon = yes
[repo gitosis-admin]
gitweb = no
daemon = no
[repo test]
gitweb = yes
daemon = yes
owner = [your@email.com]
description = A test repository
[group gitosis-admin]
writable = gitosis-admin
members = [your@email.com]
[group developers]
writable = test
members = [your@email.com]
Now we need to add, commit and push our configuration changes up to the server like so:
git add .
git commit -m "adding configuration for new repository"
git push
If the configuration was successful, you should be able to change directory back to your test repository on the host OS and issue the following command to push it up to the git server:
git push git@[git-server]:test.git master
The easiest way to test this is by navigating to your git server’s url: http://[gitserver]/git
All Done!
At this point you should be able to add repositories, manage access and add users all through the gitosis-admin repository. You should also have gitweb access running as well as public repository accessibility via git-daemon.
Hopefully this has been helpful to others out there who develop in a Windows environment but would like to use a central or shared git repository to coordinate development on their team.
Tags: git, gitosis, debian, linux, gitweb, git-daemon, source control