I have recently set up cgit over at git.sixfoisneuf.fr. I’m using Caddy as my Web server, which means that getting it to execute CGI applications took some work, as it is not possible by default.

I have installed Caddy from the Debian package repository, so I can’t use third-party plugins such as http.handlers.cgi. If downloading a custom-made Caddy version works for you, you can do it to skip the wrapper section (you will also have to adapt the Caddy configuration).

The first step will be to install cgit. Thankfully, it is already packaged by Debian:

# apt install cgit

This installs the CGI executable at /usr/lib/cgit/cgit.cgi, and some static files at /usr/share/cgit/. cgit is configured through the /etc/cgitrc file.

Let’s edit this file to point to our Git repositories hosted on our Gitea instance:

#
# cgit config
# see cgitrc(5) for details

css=/cgit-css/cgit.css
logo=/cgit-css/cgit.png

mimetype.html=text/html
mimetype.js=text/javascript
mimetype.css=text/css
mimetype.pl=text/x-script.perl
mimetype.pm=text/x-script.perl-module
mimetype.py=text/x-script.python
mimetype.png=image/png
mimetype.gif=image/gif
mimetype.jpg=image/jpeg
mimetype.jpeg=image/jpeg

root-title=
root-desc=

about-filter=/usr/lib/cgit/filters/about-formatting.sh
source-filter=/usr/lib/cgit/filters/syntax-highlighting.py

readme=:README.md
readme=:README.txt
readme=:README.html
readme=:README

scan-path=/var/lib/gitea/data/gitea-repositories/simon/

This configuration will automatically set up some common file types, as well as source code highlighting using pre-made scripts. You can customize the title and description of the root page, or remove the lines to use the defaults.

Finally, we tell cgit what our README files are usually called. They will automatically populate the “about” page of each repo.

As mentioned before, Caddy does not support CGI out of the box. However, it does support FastCGI, which is the “evolved” form of CGI. There exists several FastCGI wrappers, but we will use fcgiwrapper, which is readily available in the Debian repositories:

# apt install fcgiwrapper

Let’s also create a new systemd service to spawn cgit wrapped by fcgiwrapper:

# systemctl edit --full --force cgit.service
[Unit]
Description=CGI web interface to the Git SCM
After=network.target

[Service]
Type=exec
ExecStart=fcgiwrap -f -p "/usr/lib/cgit/cgit.cgi" -s tcp:127.0.0.1:8999

[Install]
WantedBy=multi-user.target

# systemctl start cgit

The last step will be to configure Caddy to proxy requests through FastCGI. We use two different handles, one for handling static content (served at /cgit-css/), and the other for everything else, which should go through the CGI script.

git.sixfoisneuf.fr {
        handle_path /cgit-css/* {
                root * /usr/share/cgit/
                file_server
        }

        handle {
                reverse_proxy localhost:8999 {
                        transport fastcgi {
                                env DOCUMENT_ROOT /usr/lib/cgit/
                                env SCRIPT_FILENAME /usr/lib/cgit/cgit.cgi
                        }
                }
        }
}