cgit is a web view for git repositories that is widely used and quite simple to install. This is just a brief overview over installation of cgit with Nginx on a Debian system, because I had to make a few adjustments.

First of all, of course you have to install cgit and (if not previously installed) nginx. Since cgit only provides a CGI interface, you also need to install fcgiwrap to connect Nginx to cgit. Both fcgiwrap and Nginx have to be started as services:

systemctl start nginx fcgiwrap
systemctl enable nginx fcgiwrap

On Debian, cgit web resources are stored in /usr/share/cgit and the cgit CGI script is stored in /usr/lib/cgit. This means that the Nginx document root will point to /usr/share/cgit so that the web server can deliver static resources from there, but the CGI script filename has to point to /usr/lib/cgit/cgit.cgi.

On my first attempt cgit messed up links within repositories (it duplicated the repository name in the URL). Thus, I also had to specify the virtual-root in the configuration file. According to the documentation however, this setting should not be needed if PATH_INFO is set correctly. According to a blog post the problem might be that some versions of fcgiwrap overwrite PATH_INFO. Overall, the following cgit configuration file worked for my setup:

# /etc/cgitrc

# Paths to the static resources in /usr/share/cgit (=Nginx root)
css=/cgit.css
logo=/cgit.png

# Folder containing all my repositories
scan-path=/srv/git/

# root for all cgit links
virtual-root=/

Nginx has to forward the requests to fcgiwrap which will then call the CGI script from cgit. For this, you have to setup fcgiwrap in Nginx as a FastCGI endpoint:

# /etc/nginx/sites-available/cgit.conf

server {
    listen [::]:80;
    listen 80;
 
    server_name git.example.com;

    # Path to the static web resources of cgit
    root /usr/share/cgit;

    try_files $uri @cgit;

    location @cgit {
        include             fastcgi_params;

        # Path to the CGI script that comes with cgit
        fastcgi_param       SCRIPT_FILENAME /usr/lib/cgit/cgit.cgi;

        fastcgi_param       PATH_INFO       $uri;
        fastcgi_param       QUERY_STRING    $args;
        fastcgi_param       HTTP_HOST       $server_name;

        # Path to the socket file that is created/used by fcgiwrap
        fastcgi_pass        unix:/run/fcgiwrap.socket;
    }
 
    # Used by me: Only allow this web page to be accessed on intranet,
    # even though nginx listens globally
    allow 127.0.0.1;
    allow 10.0.0.0/24;
    allow 172.16.0.0/12;
    deny all;
}

Now you can reload nginx with systemctl reload nginx and view your git repositories on http://git.example.com.

Enabling Markdown

cgit includes the possibility to display an about page from a README file, e.g. a markdown formatted README.md. To enable this, you have to adjust the file cgitrc and set the following two options:

about-filter=/usr/lib/cgit/filters/about-formatting.sh
readme=:README.md

about-formatting.sh is a helper script that calls the right formatter depending on the file extension, e.g. markdown for .md. In order for the script to work you need to have the Python package markdown installed. On Debian you can install this package with the python3-markdown.

I do not maintain a comments section. If you have any questions or comments regarding my posts, please do not hesitate to send me an e-mail to blog@stefan-koch.name.