Setting up cgit + nginx on FreeBSD
Tags: freebsd, cgit
Published: 2021-01-31 11:11:26


[cgit](https://git.zx2c4.com/cgit/about/) is a lightning-fast minimal web interface to browse git repositories. It is already package and can be easily installed in FreeBSD. This quick guide walks you through setup process. Feel free to customize it for your taste.

## Installing packages

You need to installed a few packages:

```text
# pkg install cgit nginx fcgiwrap git-lite
```

## configure git

```text
# mkdir /home/git
# chown www:www /home/git
```

## configure nginx

This is a basic configuration file for nginx looks like:

```nginx
worker_processes  1;

events {
    worker_connections  1024;
}

http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  65;
    gzip  on;

    server {
        listen       80;
        server_name  localhost;
        root /usr/local/www/cgit;
        try_files $uri @cgit;

        location @cgit {
              include fastcgi_params;
              fastcgi_param SCRIPT_FILENAME /usr/local/www/cgit/cgit.cgi;
              fastcgi_param PATH_INFO $uri;
              fastcgi_param QUERY_STRING $args;
              fastcgi_param HTTP_HOST $server_name;
              fastcgi_pass unix:/var/run/fcgiwrap/fcgiwrap.sock;
        }

        error_page   500 502 503 504  /50x.html;
        location = /50x.html {
            root   /usr/local/www/nginx-dist;
        }
    }
}
```

Enable nginx to start automatically:

```text
# sysrc nginx_enable=YES
```

And start the service:

```text
# service nginx start
```

## configure fcgiwrap

`fcgiwrap` is a light-weight FastCGI server we use to run `cgit.cgi`. It should be configured to run as `www` user and group so that nginx can communicate with it via UNIX sockets.

```text
# sysrc fcgiwrap_enable=YES
# sysrc fcgiwrap_user=www
# sysrc fcgiwrap_group=www
# sysrc fcgiwrap_socket_owner=www
# sysrc fcgiwrap_socket_group=www
```

and start the service:

```text
# service fcgiwrap start
```

## configure cgit

Edit `/usr/local/etc/cgitrc`:

```text
## style-sheet and custom logo
css=/cgit.css
logo=/cgit.png

## root for all cgit links
virtual-root=/

## syntax highlighting
source-filter=/usr/local/lib/cgit/filters/syntax-highlighting-custom.sh

## path to repo configuration file
## NOTE: This should always be the last line
include=/usr/local/etc/cgitrepos
```

And add information about your repositories to `/usr/local/etc/cgitrepos`.

You may add your repositories one by one:

```text
repo.url=MyRepo
repo.path=/home/git/myrepo.git
repo.desc=My first Git Repository
```

or multiple repositories that live under a directory:

```text
scan-path=/home/git
```

## configure syntax highlighting

```text
# pkg install highlight
```

Create a new cgit filter script (which is based on an existing script, but slightly improved):

Create `/usr/local/lib/cgit/filters/syntax-highlighting-custom.sh`:

```shell
#!/bin/sh

BASENAME="$1"
EXTENSION="${BASENAME##*.}"
[ "${BASENAME}" = "${EXTENSION}" ] && EXTENSION=txt
[ -z "${EXTENSION}" ] && EXTENSION=txt
[ "${BASENAME%%.*}" = "Makefile" ] && EXTENSION=mk

exec highlight --force -f -I -O xhtml -S "$EXTENSION" 2>/dev/null
```