HOWTO SETUP GIT WITH GITOLITE AND GITWEB - PART 1
Overview
GIT is a pretty powerful version control system, however, unlike Subversion; it is more of a pain to setup for a collaborative team. The goal of this HOWTO is to show the steps involved in setting up
- Base GIT install
- GITOLITE for multi user management/administration
- GITWEB for an HTTP GIT Repo Browser
Fine Print
I am not a security expert nor am I a complete GIT expert. This HOWTO does its best to get you up and running with GIT so your team can get to work.
Help
I found this completely awesome article to be the best resource for covering 90% of what I wrote this to smooth things out for my specific setup. If my procedure does not make sense, fall back on this one.
Assumptions
I am doing this using
- Ubuntu Linux 15.10
- GIT based on the Ubuntu distribution version
- GITWEB based on the Ubuntu distribution version
- PERL based on the Ubuntu distribution version
- GITOLITE based on a git clone from github.com
- You already have the Ubuntu distribution version of Apache2 installed and running.
My Ideal Setup
| Part |
Description |
| Server Name |
atomserver |
| Access Method |
SSH |
| GITWEB |
http://atomserver/gitweb/ |
| User Management |
GITOLITE |
| REPO Base |
/opt/data/git/repositories/ |
| GIT User |
git |
| GIT User Home |
/home/git/ |
GIT
The process for installing GIT involves installing a package and creating a user that will internally manage GIT once exposed to external systems.
Install GIT
$ sudo apt-get install git
Create a GIT user with NO Password
This user will be the user associated with the GIT REPO and will proxy between external clients and the central REPO. For this reason, it needs to be in the SSH group.
$ sudo adduser \
--system \
--shell /bin/bash \
--gecos 'git version control' \
--group \
--disabled-password \
--home /home/git \
git
$ sudo adduser git ssh
Create Location for REPO
We don’t really want to store the world’s code in a home directory so next we want to create a location that we can consider to be repo base. This assume you already have an /opt/data/ directory owned by someone.
$ sudo mkdir /opt/data/git
$ sudo mkdir /opt/data/git/repositories
$ sudo chown -R git:git /opt/data/git
Later on this repositories directory will be pointed to by a default directory in /home/git.
Checks
Ensure you can become GIT and have a /home/git directory that git owns.
$ sudo su -l git
$ pwd
$ ls -l /home
$ ls -l /opt/data
If all goes well you will see a git folder within /home/ that is owned by git and is in the git group. Same with /opt/data/
The foundation part is now done. Next step will allow your team to see the repo.
GITOLITE
GITOLITE is a proxy between GIT users and your managed GIT REPO. It support a great deal of things, however, all I need is SSH access into my REPOs.
Install
It is completely possible to get GITOLITE from yum or apt-get but you would be insane to do this since there are a few versions and the older version are a bit of a nightmare to setup based on my experience. The best approach I found in my research was to simply use the official one right off of github.
Clone GITOLITE from GITHUB
From the git user’s home directory, clone GITOLITE and then create a bin directory that will link an executable later in this process.
$ sudo su -l git
$ cd /home/git
$ git clone git://github.com/sitaramc/gitolite
$ mkdir $HOME/bin
Once done, you will see a new gitolite directory and bin directory.
Launch the GITOLIATE Setup
GITOLITE configures a few things and then creates a symlink from ./bin/ to the gitolite install directory
$ sudo su - git
$ $ cd $HOME
$ gitolite/install -ln
$ ls -l bin/gitolite
Once done, you will see a bin/gitolite symlink.
SYMLINK the main repositories to your GITOLITE HOME
Earlier a directory was created to house the git repositories. This was put outside of the git users home to allow more flexibility in moving it around. To ensure GITOLITE can see it, a symlink will be needed.
$ sudo su - git
$ cd $HOME
$ ln -s /opt/data/git/repositories/ repositories
Once completed, you will now have a new symlinked folder in the git user’s home directory for repositories.
Create RSA Key for the GIT Adminitrator
An initial RSA key will be needed for the main GIT administrator to work properly. This should be a local user on the server although other remote users can be added later on.
If you are using linux or an OS that already has .ssh installed, you will probably have $HOME/.ssh directory with an id_rsa.pub file.
If not, create an RSA key as yourself, using the following command. When asked for a passphrase, just press enter.
$ ssh-keygen -t rsa
Using your personal user (aka uuklanger in my case), copy it into the /tmp directory so it can be picked up by git and stored in the GITOLITE keydir.
$ cp ~/.ssh/id_rsa.pub /tmp/uuklanger.pub
$ sudo chown git:git /tmp/uuklanger.pub
Once completed, you will have your first Administrator GIT user key ready to go. This is the first step needed before GIT administration is possible.
Initialize gitolite_admin project
In order to be able to administer the GIT site, an administrator will need to be setup. The user will be identifed by their public key. In this case, uuklanger
$ sudo su - git
$ cd $HOME
$ bin/gitolite setup -pk /tmp/uuklanger.pub
$ rm /tmp/uuklanger.pub
When the gitolite setup is run, you will see various output showing things being created and initialized.
Once completed, you will have the first official user configured in GITOLITE as an administrator.
Administrator gitolite-admin clone
The git user .gitolite area should not be touched. It will need to be managed by your new administrator where changes can be pushed to the main gitolite repository.
For this to work, you will need your own copy of the gitolite-admin project. To get this you will need to operate as the git administrator for this server.
$ mkdir $HOME/Admin
$ mkdir $HOME/Admin/git
$ cd $HOME/Admin/git
$ git config --global user.name “UU KLanger”
$ git config --global user.email “uuklanger@sandwich.net“
$ git config --list
$ git clone git@localhost:gitolite-admin.git
Once compelted, you should have a ~/Admin/git/gitolite-admin/ folder with conf/ keydir/ in it. This is where GIT will be managed.
The ~git/.gitolite/ folder should never be touched unless there is a very good reason to
If you look at your ~/Admin/git/gitolite-admin/conf/gitolite.conf file you should see something like
repo gitolite-admin
RW+ = uuklanger
repo testing
RW+ = @all
Where uuklanger is my administrator for this GIT server.
Prepare for GITOLITE Users
It is very likely that you will access GIT from more then one machine as yourelf. However, GITOLITE indentifies you by your RSA key. To manage this, you can nest subdirectories for each platform that will connect to GITOLITE. For now, localhost is a good start.
$ cd $HOME/Admin/git/gitolite-admin/keydir
$ mkdir local
$ mkdir macbookpro
In this directory you can put all user keys that are local to this server. If you create a remote user create a directory for that client’s keys. GITOLITE will recurse the tree to validate the key.
User Setup
In order for gitolite to work securely, you will need an SSH key per user. The public key will be needed and can be easily created if it is not already in the $HOME/.ssh/.
Each user will need to submit a public key to the administrator who will place it in the ~/Admin/git/gitolite-admin/keydir/ directory. If a subdirectories were created per client, the key will need to be moved there and set with 750 permissions.
For a client to create a key, they can follow the same process used before, run the following command being sure to press enter when asked for a password.
$ ssh-keygen -t rsa
id_rsa.pub file will just need to be sent to the local admin who can put it in the keydirdirectory. Say we need to add “newguy” to git who put the key in the /tmp directory
$ cd ~/Admin/git/gitolite-admin/keydir
$ cp /tmp/newguy.pub .
$ chmod 750 newguy.pub
$ git add newguy.pub
$ cd ~/Desktop/gitolite-admin/conf
$ git add gitolite.conf
$ git commit -m “Adding new guy”
$ cd ..
$ git push origin master
$ sudo rm /tmp/newguy.pub
As project are added, gotlite.conf can be edited to give permissions to users for a given project. It is even possible to give other users admin permissions on gitolite-admin.
Checks
The git push origin master command will commit the changes into gitolite. The changes should be visible in ~git/.gitolite/.
You should have something like this for permissions
uuklanger@atomserver:/home/git$ ls -al
total 48
drwxrwxr-x 2 git git 4096 Aug 15 15:14 bin
drwxrwxr-x 6 git git 4096 Aug 15 15:12 gitolite
drwx------ 6 git git 4096 Aug 15 22:00 .gitolite
-rw------- 1 git git 6998 Aug 15 15:28 .gitolite.rc
-rwxrwxr-x 1 git git 12 Aug 24 08:24 projects.list
lrwxrwxrwx 1 git git 27 Aug 15 17:53 repositories -> /opt/data/git/repositories/
drwx------ 2 git git 4096 Aug 24 08:24 .ssh
to ensure that outside processes can see.
GITWEB
In order to allow someone to browse a GIT repo without a full GIT install, GITWEB has been created. This tool lets you look around and navigate your source tree.
For this to work you will need apche2 installed with cgi support enabled.
Install
Running UBUNTU, gitweb can be installed using apt
$ sudo apt-get install gitweb
This will provide the core install in /usr/share/gitweb/ along with
- /etc/gitweb.conf
- /etc/apache2/conf-{available, enabled}/gitweb.conf
With the base setup, the configuration is needed next.
Configuration of Apache
Edit /etc/apache2/conf-available/gitweb.conf
Alias /gitweb /usr/share/gitweb
<Directory /usr/share/gitweb>
SetEnv GITWEB_CONFIG /etc/gitweb.conf
DirectoryIndex gitweb.cgi
Allow from all
AllowOverride all
Order allow,deny
Options +ExecCGI +FollowSymLinks
AddHandler cgi-script .cgi
<Files gitweb.cgi>
SetHandler cgi-script
</Files>
RewriteEngine on
RewriteRule ^[a-zA-Z0-9_-]+.git/?(\?.)?$ /gitweb.cgi%{REQUESTURI} [L,PT]
</Directory>
Ensure that this configuration file is symlinked in ../conf-enabled/gitweb.conf
Configuration of gitweb
Edit /etc/gitweb.conf to to look as follows. Ensure that the extra attention is paid to $projectroot
# 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;
$projects_list = "/home/git/projects.list";
# stylesheet to use
@stylesheets = ("/static/gitweb.css");
# javascript code for gitweb
$javascript = "/static/gitweb.js";
# logo to use
$logo = "/static/git-logo.png";
# the 'favicon'
$favicon = "/static/git-favicon.png";
# git-diff-tree(1) options to use for generated patches
#@diff_opts = ("-M");
@diff_opts = ();
In addition, as the user git, the .gitolite.rc file will need to be updated to change the UMASK.
$ sudo su - git
$ cd $HOME
$ vi .gitolite.rc
Near the top of the file, there will be a UMASK configuration. The default 0077 but should be set to 0027.
Once done, the gitweb.conf file will be pointing to the correct locations for things like the project root and list.
Visible Repos using projects.list
The repos that are visible can be managed in the the git user home.
An example project list
$ sudo su - git
$ cd $HOME
$ cat projects.list
testing.git
As you can see, we only have one project in this list. If you need to add more then simply have a single line project.
$ sudo su - git
$ cd $HOME
$ vi projects.list
Once completed, you should have a projects.list that works.
Project Repositories Permissions
The directory where the repositories are stored will need their permissions confirmed. Best way is to force them to be as you wish.
$ sudo chmod +R 750 /opt/data/git/repositories
When new projects are added, this level of permissions will be set for each new *.git created automatically based on the UMASK set earlier. To ensure that apache2 can see the repos, www-data will needed added to the git group.
$ sudo adduser www-data git
To test to see if gitweb works, try the following where we are assuming gitweb is installed /usr/share/gitweb/ …
$ sudo su - git
$ /usr/share/gitweb/gitweb.cgi
If everything works well, you should see your projects listed in the returned HTML.
Since Apache runs as a different user, the only true way to confirm this works is using Apache. For that to happen all the configuraiton will need activated.
Activation
After all configuration is completed apache will need to be restarted.
$ sudo service apache2 restart
Apache should restart without any errors.
Checks
Once restarted it should be possible to navigate to
http://HOSTNAME/cgi-bin/gitweb/
or
http://HOSTNAME/gitweb/
If you get back your project list, then you are in and should be able to fully navigate your code trees based on the repository permissions (r-x for world) and what is stored in the projects.list file for the git user.
Conclusions
Based on this you will hopefully have a base to start with for GIT. If you do not understand why a step was done above, research it to ensure it is understood and agreed.
Created 20-November–2015 by uuklanger
Updated 06-December–2015 by uuklanger
Updated 23-December–2015 by uuklanger
