Merge branch 'master' of /srv/git/gitweb-sgk

[gitweb-sgk] / README.md

# Overview #

This is a fork of `gitweb` containing customizations used on
<http://git.subgeniuskitty.com>.

Changes include defaulting to side-by-side diffs, automatically displaying
README files when present, and a new summary page.

# Status #

Working. Tested on <http://git.subgeniuskitty.com>.

# Instructions #

The following instructions work on Debian 10. All paths are examples from
the SGK gitweb server located at <http://git.subgeniuskitty.com>. For more
details, including accompanying scripts, see sysadmin notes on
<http://subgeniuskitty.com>.

-----

Verify prequisites are installed. Syntax highlighting is provided by
`highlight` and markdown-to-HTML processing is provided by `discount`.

    apt-get install gitweb highlight discount

Create a Gitweb configuration file at `/etc/gitweb.conf`. For example,
<http://git.subgeniuskitty.com> uses the following configuration file.

    $site_name = "git.subgeniuskitty.com";
    @git_base_url_list = ("git://git.subgeniuskitty.com");
    $projectroot = "/srv/gitweb_cache";
    $git_temp = "/tmp";
    
    @stylesheets = ("static/gitweb.css");
    $javascript = "static/gitweb.js";
    $logo = "static/sgk-logo.png";
    $favicon = "static/git-favicon.png";
    
    # git-diff-tree(1) options to use for generated patches
    @diff_opts = ();
    
    # Enable PATH_INFO so the server can produce URLs of the
    # form: http://git.hokietux.net/project.git/xxx/xxx
    # This allows for pretty URLs *within* the Git repository,
    # also needs the Apache rewrite rules for full effect.
    $feature{'pathinfo'}{'default'} = [1];
    
    # HTML text to include as home page header.
    $home_text = "indextext.html";
    
    # Add a toolbar option with the 'git clone url'.
    $feature{'actions'}{'default'} = [('clone url', 'git://git.subgeniuskitty.com/%n', 'summary')];
    
    # Category name is read from .git/category, in the same manner as .git/description.
    $projects_list_group_categories = 1;
    $project_list_default_category = "misc";
    
    # Needed for displaying README files.
    $prevent_xss = 0;
    
    ################################################################################
    
    # Enable blame, pickaxe search, snapshop, search, and grep
    # support, but still allow individual projects to turn them off.
    # These are features that users can use to interact with your Git trees. They
    # consume some CPU whenever a user uses them, so you can turn them off if you
    # need to.  Note that the 'override' option means that you can override the
    # setting on a per-repository basis.
    $feature{'blame'}{'default'} = [1];
    $feature{'blame'}{'override'} = [1];
    
    $feature{'pickaxe'}{'default'} = [1];
    $feature{'pickaxe'}{'override'} = [1];
    
    $feature{'snapshot'}{'default'} = [1];
    $feature{'snapshot'}{'override'} = [1];
    
    $feature{'search'}{'default'} = [1];
    
    $feature{'grep'}{'default'} = [1];
    $feature{'grep'}{'override'} = [1];
    
    $feature{'highlight'}{'default'} = [1];

Create an Apache vhost definition among the Apache2 configuration files. For
the Debian 10 server that runs <http://git.subgeniuskitty.com>, this means
creating the file `/etc/apache2/sites-available/git.subgeniuskitty.com/conf`
with the following contents.

    <VirtualHost *:80>
            ServerName git.subgeniuskitty.com
            ServerAdmin webmaster@subgeniuskitty.com
    
            DocumentRoot "/srv/apache_vhosts/git.subgeniuskitty.com"
    
            ErrorLog /var/log/apache2/error_log.git.subgeniuskitty.com
            CustomLog /var/log/apache2/access_log.git.subgeniuskitty.com combined
    
            <Directory "/srv/apache_vhosts/git.subgeniuskitty.com">
                    Options +FollowSymLinks +ExecCGI
                    AllowOverride None
                    Require all granted
                    AddHandler cgi-script .cgi
                    DirectoryIndex gitweb.cgi
                    RewriteEngine On
                    RewriteCond %{REQUEST_FILENAME} !-f
                    RewriteCond %{REQUEST_FILENAME} !-d
                    RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
            </Directory>
    </VirtualHost>

Clone a copy of the gitweb repository into the vhost's webroot. Ensure it is
owned by an SSH-enabled user for management, and that permissions are suitable
for reading by the Apache2 user, usually `www-data` on Debian.

    mkdir -p /srv/apache2_vhosts
	git clone /srv/git/gitweb-sgk /srv/apache2_vhosts/git.subgeniuskitty.com
	chown -R ataylor:ataylor /srv/apache2_vhosts/git.subgeniuskitty.com

In order to maintain a public/private split, gitweb only displays repos that
have been cloned into `/srv/gitweb_cache`.  Remember to set `.git/description`
and `.git/category` for any repos cloned into this gitweb cache folder.

	mkdir -p /srv/gitweb_cache
	git clone /srv/git/repo_name /srv/gitweb_cache/repo_name
	echo "A description goes here." > /srv/gitweb_cache/repo_name/.git/description
	echo "Category" > /srv/gitweb_cache/repo_name/.git/category
	printf '#!/usr/bin/bash\ncd /srv/gitweb_cache/repo_name/.git\ngit pull\n' > /srv/git/repo_name/hooks/post-update
	chmod +x /srv/git/repo_name/hooks/post-update

Turn everything on.

	a2enmod cgi
	a2enmod rewrite
	a2ensite git.subgeniuskitty.com
	systemctl reload apache2