Setting up cgit on Debian

cgit is a lightweight web interface for Git repositories. It's easy to set up, and provides a clean, minimal, read-only view of your repositories. This makes it ideal for use cases such as hosting personal repositories on a Raspberry PI through to hosting the Linux kernel. This post is quickly going to go over setting up cgit on Debian , however cgit is packaged for several different distributions.

Installing cgit

cgit can be installed from the Debian repositories using apt:

apt-get install cgit

For the example in this post I'm going to use Pygments for syntax highlighting, and Apache as the web server, however alternatives can be used. I'm also going to install Git. Again packages can be installed using apt:

apt-get install python3-pygments apache2 git

Creating a test repository

For the example in this post, repositories are going to be stored in /var/git/.

mkdir /var/git
chown root:www-data /var/git
chmod 750 /var/git

Note: on Debian the Apache process is run as the www-data user. This user to be able to read repository files, however write access is not required.

git init can be used to create a bare git repository in the directory:

git init --bare /var/git/example.git

It's also worth updating the repository description:

echo 'Hello world' > /var/git/example.git/description

Configuring Apache and cgit

On Debian the cgit package deploys the following configuration to /etc/apache2/conf-available/cgit.conf:

ScriptAlias /cgit/ "/usr/lib/cgit/cgit.cgi/"
RedirectMatch ^/cgit$ /cgit/
Alias /cgit-css "/usr/share/cgit/"
<Directory "/usr/lib/cgit/">
   AllowOverride None
   Options ExecCGI FollowSymlinks
   Require all granted
</Directory>

This config, along with mod_cgid, can be enabled using a2enconf and a2enmod:

$ a2enconf cgit
Enabling conf cgit.
To activate the new configuration, you need to run:
  systemctl reload apache2

$ a2enmod cgid
Enabling module cgid.
To activate the new configuration, you need to run:
  systemctl restart apache2

The actual configuration for cgit lives in /etc/cgitrc. For this post I used the following configuration:

# use default logo and CSS
css=/cgit-css/cgit.css
logo=/cgit-css/cgit.png

# set default repo readme file
readme=README.md

# allow repository cloning via HTTP
enable-http-clone=1

# enable Pygments syntax highlighting
source-filter=/usr/lib/cgit/filters/syntax-highlighting.py

# specify repository folder
scan-path=/var/git

Note: refer to the cgitrc man page for more info on valid options.

Finally Apache can be restarted to pick up the configuration changes:

  systemctl restart apache2

If everything goes well you should now be able to go to http://somehost/cgit/ in a web browser and get a page similar to the following:

It should also be possible to clone the example.git repository created earlier over HTTP:

git clone http://somehost/cgit/example.git