How I setup cgit for a browsable liveslak repository

I received a request to document how I configured the backend for https://git.liveslak.org/ . This is where my git repository for liveslak is accessible and browseable using cgit as the engine.
Of course the server is also running an actual git repository service which people use to clone the liveslak files and for me to upload changes.
Setting up git is not hard, but it’s beyond the scope of this blog article. Also, setting up Let’s Encrypt to create a secure (https) web site is not in the scope of this article but you can read my Let’s Encrypt article of course.

I’ll explain the steps that are needed to create a cgit webserver in the text below.
First we build and install cgit as well as its dependencies; then we create the cgit configuration and add some customization. Lastly we configure Apache httpd so that it knows what to serve.

Let’s start with building the required packages in order. In case you are running Slackware -current (i.e. newer than 15.0) then the lua package is already included in the core distro, so you can skip compiling it now:

• lua
• luacrypto
• lua-md5
• highlight
• cgit

You can find build scripts for all of them on the SlackBuilds.org (SBo) web site.
The lua* and highlight packages are needed for syntax highlighting, and lua is also needed for gravatar support.
The cgit package has customization added by the SBo admins which we are going to use, notably support for displaying the committers’ gravatar images.

Once you have built and installed the above packages, create a new directory to hold our custom cgit stuff:

# mkdir -p /home/www/cgit

Create some symlinks to the files that were installed by the Slackware cgit package:

# ln -s /var/www/cgi-bin/cgit.cgi /home/www/cgit/
# ln -s /var/www/cgi-bin/cgit.js /home/www/cgit/
# ln -s /var/www/cgi-bin/cgit.png /home/www/cgit/

But make a copy, not a symlink, of the CSS file:

# cp -ia /var/www/cgi-bin/cgit.css /home/www/cgit/

Some additional CSS code needs to be added to cgit.css to make the committer avatars hover properly. Here’s the lines to append to the file copy we just made (you will find this same code in the file /usr/doc/cgit-*/email-gravatar-sbo-additions.css which is part of the Slackware cgit package):

div#cgit span.gravatar img.onhover {
    display: none;
    border: 1px solid gray;
    padding: 0px;
    -webkit-border-radius: 4px;
    -moz-border-radius: 4px;
    border-radius: 4px;
    width: 128px;
    height: 128px;
}
div#cgit span.gravatar img.inline {
    -webkit-border-radius: 3px;
    -moz-border-radius: 3px;
    border-radius: 3px;
    width: 13px;
    height: 13px;
    margin-right: 0.2em;
    opacity: 0.8;
}
div#cgit span.gravatar:hover > img.onhover {
    display: block;
    position: absolute;
    margin-left: 1.5em;
    background-color: #eeeeee;
    box-shadow: 5px 5px 3px #bbb;
}

We also need to tweak the syntax-highlighting.sh script (part of the cgit package) a bit so it works better for us Slackers.
Make a copy of it, removing all comments:

# grep -Ev '(#$|^ *#)' /usr/share/cgit/filters/syntax-highlighting.sh > /home/www/cgit/syntax-highlighting.sh
# chmod +x /home/www/cgit/syntax-highlighting.sh

And then add these lines right before the final ‘exec’ line of the script:

# map SlackBuild to .sh
[ "$EXTENSION" == "SlackBuild" ] && EXTENSION=sh

To make the git.liveslak.org website stand out from others, I substituted my own frontpage image and a custom favicon image. These are created as /home/www/cgit/eric_hameleers.png (link) and /home/www/cgit/erichameleers_favicon.ico (link) and both filenames are referenced further down in the cgit configuration.
By default, cgit will look for a file called “/etc/cgitrc” to read its configuration, but I am running multiple sites on a single Slackware host (git.slackware.nl for instance), therefore I create a separate cgit configuration file for each site. For liveslak, it is called “/etc/cgitrc.git.liveslak.org” and then I instruct Apache httpd to look for that particular filename.

/etc/cgitrc.git.liveslak.org

# For more options, see cgitrc.5.txt in the docs folder
root-title=Alien BOB's
root-desc=Web interface to liveslak git repository
virtual-root=/
snapshots=tar.gz tar.xz

summary-branches=10
summary-log=10
summary-tags=10

repository-sort=date
commit-sort=date
branch-sort=age

enable-blame=1
enable-index-links=1
enable-commit-graph=1
enable-follow-links=1
enable-log-filecount=1
enable-log-linecount=1
max-stats=quarter

mimetype-file=/etc/httpd/mime.types
mimetype.rss=application/rss+xml
enable-html-serving=1

css=/cgit.css
logo=/eric_hameleers.png
favicon=/erichameleers_favicon.ico

about-filter=/usr/share/cgit/filters/about-formatting.sh

# for this to work you have to build cgit against lua
# and install luacrypto too
email-filter=lua:/usr/share/cgit/filters/email-gravatar-sbo.lua

# For this to work, you need lua and highlight packages:
source-filter=/home/www/cgit/syntax-highlighting.sh

repo.url=liveslak
repo.path=/path/to/repositories/liveslak.git
repo.desc=Slackware Live Edition by AlienBOB
repo.owner=alien@slackware.com
repo.clone-url=git://liveslak.org/liveslak.git
repo.readme=:README.txt

The actual definition for the git repository is the lines at the end starting with “repo.“.

Lastly, the Apache web server needs to be configured to serve our cgit stuff whenever someone visits git.liveslak.org.
These are the files used to accomplish that:

/etc/httpd/extra/git.liveslak.org.conf

(just an example filename, you will know how and where to add the content for your specific Apache configuration):

<VirtualHost *:80>
    ServerName git.liveslak.org
    ServerAdmin alien@slackware.com

    CustomLog /var/log/httpd/git.liveslak.org_access_log combined
    ErrorLog /var/log/httpd/git.liveslak.org_error_log

    # Include Let's Encrypt configuration:
    Include /etc/httpd/extra/letsencrypt.conf

    # Include the site definition (AFTER Let's Encrypt configuration!!):
    Include /etc/httpd/extra/git.liveslak.org_content.conf
</VirtualHost>
<VirtualHost *:443>
    ServerName git.liveslak.org
    ServerAdmin alien@slackware.com

    CustomLog /var/log/httpd/git.liveslak.org-ssl_access_log combined
    ErrorLog /var/log/httpd/git.liveslak.org-ssl_error_log

    # Include Let's Encrypt configuration:
    Include /etc/httpd/extra/letsencrypt.conf

    # Include web server generic SSL configuration for vhosts:
    Include /etc/httpd/extra/ssl_vhost.conf

    # Include the site definition (AFTER Let's Encrypt configuration!!):
    Include /etc/httpd/extra/git.liveslak.org_content.conf
</VirtualHost>

The file “git.liveslak.org_content.conf” is included twice in the above VirtualHost definition file for Apache. Using these “Include” lines prevents some duplication of code.
Here is the content of that included file:

/etc/httpd/extra/git.liveslak.org_content.conf

DocumentRoot /home/www/cgit
Options FollowSymlinks

# Use a custom name for the configuration - default is /etc/cgitrc:
SetEnv CGIT_CONFIG /etc/cgitrc.git.liveslak.org

DirectoryIndex cgit.cgi
AllowOverride none
Require all granted

SetHandler cgi-script

Options ExecCGI
Require all granted

Alias /cgit.css /home/www/cgit/cgit.css
Alias /cgit.png /home/www/cgit/cgit.png
Alias /erichameleers_favicon.ico /home/www/cgit/erichameleers_favicon.ico
Alias /eric_hameleers.png /home/www/cgit/eric_hameleers.png
Alias /robots.txt /home/www/cgit/robots.txt
Alias / /home/www/cgit/cgit.cgi/

I hope that this story may help some of you with getting your own browseable git repository online.

Good luck, Eric