Rel4tion-Wiki/maint/admin/Git_Server/Web_Interface_using_Gitweb.mdwn

On the gitolite side, you enable repositories to be served via the web interface
by doing one of these:

1. Give read permission to the special user 'gitweb'
2. Add a gitweb config line to gitolite.conf

The second option allows you to specify a description and an owner for the
repository, so let's use that. For example, let's enable the cool-project
repository to appear on the web interface and give it a description. We just
need to add the following line somewhere in gitolite.conf:

	cool-project = "A very cool project"

We can also add an owner:

	cool-project "Alice Sandler" = "A very cool project"

gitolite.conf now may look like this:

	repo    gitolite-admin
	        RW+     =   alice
	
	repo    cool-project
	        RW+     =   alice h4ck3r
	        R       =   daemon
	
	cool-project = "A very cool project"

Of course the change must be committed and pushed to take effect.

Now, that was just the gitolite side. We still need a webserver to serve the web
pages, and Gitweb itself to generate them from the repository information. So
the steps left are:

1. Install packages
2. Configure gitweb
3. Configure the web server

We'll use lighttpd as the webserver. Alternatively you may prefer Nginx or
Apache or something else. If you do, check their documentation to see how to
configure them. Gitweb comes with a config file for Apache, but I'm not sure it
works (if it does, it definitely saves you the step of configuring the server).

Assume your website name is mysite.org. Later we'll see what to do for I2P. Git
browsing will be available at git.mysite.org.

Let's start by installing packages. Run this as root:

	# apt-get install lighttpd gitweb highlight

After this, browsing to your server using a web browser should load the default
page provided by Debian. It will suggest that you replace it. If you already had
a website you won't see that page of course. Anyway, we're going to add the
gitweb interface there.

Now let's configure Gitweb. We need to tell it where to look for the
repositories and give it a list of repositories to serve. By default it just
serves everything it finds, but we will let gitolite.conf control what gitweb
serves by making gitweb use the project list generated by gitolite. Here's what
the config file should look like after installation:

	# path to git projects (<project>.git)
	$projectroot = "/var/cache/git";
	
	# 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
	#@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 = ();

Now, here's our updated file. See `man gitweb.conf` for full documentation of
what can be set in the configuration file.

	################ directories ###############################################
	
	## path to git projects (<project>.git)
	#$projectroot = "/var/cache/git";
	$projectroot = "/home/git/repositories";
	
	# directory to use for temp files
	$git_temp = "/tmp";
	
	################ access control ############################################
	
	## file with project list; by default, simply scan the projectroot dir.
	#$projects_list = $projectroot;
	## use the list generated by gitolite
	$projects_list = "/home/git/projects.list";
	
	## a repository will be accessed by gitweb only if it contains this file
	## this is the same file used by git-daemon, to help prevent mistakes
	$export_ok = "git-daemon-export-ok";
	
	## choose whether access control controls what appears in the overview, or
	## also controls what can be accessed at all, i.e. only allow viewing
	## repositories which are also shown in the overview
	$strict_export = "true";
	
	################ links and their targets ###################################
	
	## stylesheets to use
	@stylesheets = ("static/gitweb.css");
	
	## logo to use
	$logo = "static/git-logo.png";
	
	## the 'favicon'
	$favicon = "static/git-favicon.png";
	
	## target of the home link on top of all pages
	#$my_uri = "http://git.mysite.org";
	
	## label for the home link
	$home_link_str = "Projects";
	
	## where the logo image links
	$logo_url = "http://www.mysite.org";
	
	## label for the logo image
	$logo_label = "MySite";
	
	################ look ######################################################
	
	## site name to appear in page titles
	$site_name = "MySite Git Repositories";
	
	## name of HTML file to be included at the top of each page
	#$site_header =
	
	## name of HTML file to be included at the bottom of each page
	#$site_footer =
	
	## name of HTML file to be included in the projects overview
	#$home_text = "$projectroot/indextext.html";
	
	## width of the description column in the overview
	$projects_list_description_width = 25;
	
	################ other features and policies ###############################
	
	## list of base URLs which can be used for cloning repositories
	@git_base_url_list = ('git://git.mysite.org',
	                      'ssh://git@git.mysite.org',
	                      'http://git.mysite.org');
	
	## whether to enable categories in the overview
	$projects_list_group_categories = "true";
	
	## disable some potentially CPU-intensive features
	$feature{'blame'}{'default'} = [undef];
	$feature{'grep'}{'default'} = [undef];
	$feature{'pickaxe'}{'default'} = [undef];
	$feature{'search'}{'default'} = [undef];
	
	## enable features
	$feature{'highlight'}{'default'} = [1];
	
	## git-diff-tree(1) options to use for generated patches
	#@diff_opts = ("-M");
	@diff_opts = ();

Gitweb is now ready to use, but our webserver doesn't know about it yet. We need
to have a link or a path on the website which leads to the Gitweb interface, and
we need to make sure the webserver is able to serve Gitweb's perl module (since
it's not plain static HTML).

Before that, one more thing: The webserver can't read any git content without
read access. We need to add the webserver user to the __git__ group, like we did
for gitdaemon. The default server username is 'www-data' so this command should
give the permissions, run as root:

	# adduser www-data git

Time to configure the webserver and we're done. There are many possible
configurations depending on your specific setup and what else your server does,
so we'll do one possible setup: a website at mysite.org and the gitweb interface
at git.mysite.org.

The first thing we'll do is review the initial server setup. This is what Debian
comes with:

	server.modules = (
	        "mod_access",
	        "mod_alias",
	        "mod_compress",
	        "mod_redirect",
	#       "mod_rewrite",
	)
	
	server.document-root        = "/var/www"
	server.upload-dirs          = ( "/var/cache/lighttpd/uploads" )
	server.errorlog             = "/var/log/lighttpd/error.log"
	server.pid-file             = "/var/run/lighttpd.pid"
	server.username             = "www-data"
	server.groupname            = "www-data"
	server.port                 = 80
	
	
	index-file.names            = ( "index.php", "index.html", "index.lighttpd.html" )
	url.access-deny             = ( "~", ".inc" )
	static-file.exclude-extensions = ( ".php", ".pl", ".fcgi" )
	
	compress.cache-dir          = "/var/cache/lighttpd/compress/"
	compress.filetype           = ( "application/javascript", "text/css", "text/html", "text/plain" )
	
	# default listening port for IPv6 falls back to the IPv4 port
	include_shell "/usr/share/lighttpd/use-ipv6.pl " + server.port
	include_shell "/usr/share/lighttpd/create-mime.assign.pl"
	include_shell "/usr/share/lighttpd/include-conf-enabled.pl"

This is much shorter than the sample files provided by lighttpd, but it also has
no comments to explain what's going on. Let's add comments and add the gitweb
host:

	## core modules used by the server
	## mod_access: deny access to files with specific extensions (e.g. backup files)
	## mod_alias: specify special document root for a url subset
	## mod_compress: compress static content to reduce network load
	## mod_redirect: redirect a set of URLs externally
	server.modules = (
	        "mod_access",
	        "mod_alias",
	        "mod_compress",
	        "mod_redirect",
	#       "mod_rewrite",
	)
	
	## basic setup
	server.document-root        = "/var/www"
	server.upload-dirs          = ( "/var/cache/lighttpd/uploads" )
	server.errorlog             = "/var/log/lighttpd/error.log"
	server.pid-file             = "/var/run/lighttpd.pid"
	server.username             = "www-data"
	server.groupname            = "www-data"
	server.port                 = 80
	
	## filenames to be used as directory index
	index-file.names            = ( "index.cgi", "index.html" )
	
	## deny access to some files by pattern
	url.access-deny             = ( "~", ".inc" )
	
	## avoid serving dynamic content generators as static content
	static-file.exclude-extensions = ( ".php", ".pl", ".fcgi" )
	
	## directory to use for caching compressed content
	compress.cache-dir          = "/var/cache/lighttpd/compress/"
	
	## which file types to compress
	compress.filetype           = ( "application/javascript", "text/css", "text/html", "text/plain" )
	
	## default listening port for IPv6 falls back to the IPv4 port
	include_shell "/usr/share/lighttpd/use-ipv6.pl " + server.port
	
	## create mime types
	include_shell "/usr/share/lighttpd/create-mime.assign.pl"
	
	## enable the modules enabled via `lighty-enable-mod` (the conf-enabled folder)
	include_shell "/usr/share/lighttpd/include-conf-enabled.pl"
	
	## gitweb host
	$HTTP["host"] == "git.mysite.org" {
	    server.document-root = "/usr/share/gitweb"
	    cgi.assign = (
	        ".cgi" => "/usr/bin/perl"
	    )
	}

Now run this as root to enable CGI:

	# lighty-enable-mod cgi

Done.

How to set a local setup: If you have a domain name, you can use it easily. For
example, make sure mysite.org loads the website while git.mysite.org loads the
gitweb interface. If you don't, you'll use localhost or 127.0.0.1 to browse the
local server, but you need to somehow tell the server how to use the gitweb
host. In general, you need a way to pass a "fake" host, and use that host as the
gitweb host in the configuration above. Then localhost will take you to the
website and the fake host will take you to the gitweb interface.

For me, a very simple setup worked: I set the gitweb host to 'localhost', and
then 127.0.0.1 took me to the website while localhost took me to gitweb. I don't
know what happens if you have more virtual hosts on your machine, but for the
configuration described above it's an easy way to test what we did so far.