Sunday, December 13, 2015

HOWTO SETUP GIT WITH GITOLITE AND GITWEB - PART 1

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

Posted by at
Labels: , , , ,

No comments:

Post a Comment

Subscribe to: Post Comments (Atom)