getting cgit up and running

This is a small collection of notes how I have setup cgit.

Cgit is a small binary, that only handles the CGI protocol. Most webservers don’t have any support for CGI left, apache being the only one that still has it.

Therefore a translation is needed from incoming HTTP to CGI.

The webserver for this use case is caddy and the translation part is done by a small Go tool I developed, gocgi

configuration of caddy

The configuration must handle two cases

1. forwarding to cgit
2. serving assets

The split can be achieved with the following

git.example.com {
    encode zstd gzip
    handle_path /assets/* {
        file_server {
            root /usr/share/webapps/cgit/
        }
    }

    handle /* {
        reverse_proxy unix//run/gocgi/git.example.com.sock
    }
}

configuration of gocgi

Gocgi only needs to handle forwarding HTTP requests to the CGI binary.

Create a config file in /etc/gocgi and adjust the parameters

# Path to the binary to call when a request was accepted.
GOCGI_BIN="/usr/lib/cgit/cgit.cgi"
# Set a number of environment variables to give to the binary.
GOCGI_ENV="CGIT_CONFIG=cgitrc"
# Set the working directory for this instance.
GOCGI_WORKDIR="/srv/git/"

By setting CGIT_CONFIG we are telling it to look for the config in a different place, in this case relative to GOCGI_WORKDIR.

configuration of cgit

Lastly the cgitrc file.

#cache-size=1000

title="git.example.com"
root-desc="git repositories"

# create a nice https clone URL.
clone-prefix=https://git.example.com/

# Point to the correct asset locations.
css=/assets/cgit.css
favicon=/assets/favicon.ico
logo=/assets/cgit.png
js=/assets/cgit.js

# load git config for futher options.
enable-git-config=1
enable-http-clone=1
enable-blame=1

# Show number of affected files per commit on the log pages
enable-log-filecount=1
# Show number of added/removed lines per commit on the log pages
enable-log-linecount=1

# about-formatting.sh handles all formatting options.
# It requires the markdown and pygments python packages to be available
# to function properly.
about-filter=/usr/lib/cgit/filters/about-formatting.sh

# search for README files.
readme=:README.md
readme=:README

# Scan the directory for all git repositories.
scan-path=.

creating repositories

To create a new repository ready for being served, use the following command:

$ git init --bare /srv/git/reponame

fix the go get header

To make a git repository go gettable, an extra header needs to be set. This can only be done on a repository basis.

The config option must be added to the config file of the bare repository. As an example, this sets the import path for a repository foobar on the domain git.example.com.

[cgit]
    extra-head-content=<meta name=\"go-import\" content=\"git.example.com/foobar git https://git.example.com/foobar\">