cGit-UI — a web interface for Git Repositories

cGit-UI — is a web interface for Git repositories. cGit-UI is based on CGI script written in С.

This article covers installing and configuring cGit-UI to work using Nginx + uWsgi. Setting up server components is quite simple and practically does not differ from setting up cGit.

cGit-UI supports Markdown files that are processed on the server side using the md4c library, which has proven itself in the KDE Plasma project. cGit-UI provides the ability to add site verification codes and scripts from systems such as Google Analytics and Yandex.Metrika for trafic analysis. Users who wonder to receive donations for his projects can create and import custom donation modal dialogs.

Instead of looking at screenshots, it is better to look at the working site to decide on installing cGit-UI on your own server.

Reqired Packages

cGit-UI depends of following libraries: libpcre2, libmd4c, libmd4c-html, libmagic, and libgit2.

Also cGit-UI depends on the cScm package. Therefore, before installing cGit-UI, you have to install and configure cScm Configuration Daemon.

To use cGit-UI a web server must be installed and configured on the system. We recommend the Nginx with uWsgi application server. Of course, Git SCM system should be installed too.

Installation

To obtain sources we have to checkout its from SVN repository:

svn checkout svn://radix.pro/cgit-ui/tags/cgit-ui-0.1.4 cgit-ui-0.1.4

and run the bootstrap script:

cd csvn-0.1.4
./bootstrap

Also cGit-UI source packages are available for download on the Radix.pro FTP-server.

Bootstrap Script

The bootstrap script especially created for Autotools install automation. To install Autotools into the source directory on the build machine (i.e. when build == host) the bootstrap script can be run without arguments.

./bootstrap

In this case Autotools will be installed from current root file system.

For the cross environment the --target-dest-dir option allows to install some stuff from development root file system:

TARGET_DEST_DIR=/home/developer/prog/trunk-672/dist/.s9xx-glibc/enybox-x2 \
    ./bootstrap --target-dest-dir=${TARGET_DEST_DIR}

For example, in this case the aclocal.m4 script will be collected from the
${TARGET_DEST_DIR}/usr/share/aclocal directory.

Configuring Sources

./configure --prefix=/usr \
            --with-scriptdir=/var/www/htdocs/cgit

Install on the Build Machine

make
make install

Cross Compilation Example

#!/bin/sh

TARGET_DEST_DIR=/home/developer/prog/trunk-672/dist/.s9xx-glibc/enybox-x2
TOOLCHAIN_PATH=/opt/toolchains/aarch64-S9XX-linux-glibc/1.1.4/bin
TARGET=aarch64-s9xx-linux-gnu

./bootstrap --target-dest-dir=${TARGET_DEST_DIR}

PKG_CONFIG=/usr/bin/pkg-config \
PKG_CONFIG_PATH=${TARGET_DEST_DIR}/usr/lib${LIBDIRSUFFIX}/pkgconfig:${TARGET_DEST_DIR}/usr/share/pkgconfig \
PKG_CONFIG_LIBDIR=${TARGET_DEST_DIR}/usr/lib${LIBDIRSUFFIX}/pkgconfig:${TARGET_DEST_DIR}/usr/share/pkgconfig \
STRIP="${TOOLCHAIN_PATH}/${TARGET}-strip" \
CC="${TOOLCHAIN_PATH}/${TARGET}-gcc --sysroot=${TARGET_DEST_DIR}" \
./configure --prefix=/usr
  --build=x86_64-pc-linux-gnu \
  --host=${TARGET} \
  --with-scriptdir=/var/www/htdocs/cgit

make
make install DESTDIR=${TARGET_DEST_DIR}

Also we can make use of additional variables such as CFLAGS, LDFLAGS:

LDFLAGS="-L${TARGET_DEST_DIR}/lib -L${TARGET_DEST_DIR}/usr/lib"
TARGET_INCPATH="-L${TARGET_DEST_DIR}/usr/include"
CFLAGS="${TARGET_INCPATH}"
CPPFLAGS="${TARGET_INCPATH}"

Post Install

The system user, on whose behalf the Nginx server is launched, must have permissions to access the directory in which the cGit-UI CGI script was installed:

chown -R nginx:nginx /var/www/htdocs/cgit

Additionaly if nginx user has not enough permissions to access repositories we have to change owner of /var/www/htdocs/cgit/cgit-ui.cgi script and set SUID or SGID bit:

chown -R 0:0 /var/www/htdocs/cgit/cgit-ui.cgi
chmod 4755 /var/www/htdocs/cgit/cgit-ui.cgi

uWsgi

Since we used the --with-scriptdir=/var/www/htdocs/cgit option on configuring stage, the cGit-UI CGI script installed in the /var/www/htdocs/cgit/ directory. In this case, the /etc/uwsgi/cgit-ui.ini file should look like this:

/etc/uwsgi/cgit-ui.ini:

[uwsgi]
master          = true
plugins         = cgi
socket          = /run/uwsgi/%n.sock
uid             = nginx
gid             = nginx
procname-master = uwsgi cgit-ui
processes       = 1
threads         = 2
cgi             = /var/www/htdocs/cgit/cgit-ui.cgi

Where /var/www/htdocs/cgit/cgit-ui.cgi is the full name of installed cGit-UI CGI script.

To run the uWSGI daemon for cGit-UI backend we can make use following start/stop script:

/ets/rc.d/rc.cgit-ui-uwsgi:

#!/bin/sh
#
# uWSGI daemon control script.
#

CONF=cgit-ui
BIN=/usr/bin/uwsgi
CONFDIR=/etc/uwsgi
PID=/var/run/$CONF-uwsgi.pid

uwsgi_start() {
  # Sanity checks.
  if [ ! -r $CONFDIR/cgit-ui.ini ]; then # no config files, exit:
    echo "There are config files in $CONFDIR directory. Abort."
    exit 1
  fi

  if [ -s $PID ]; then
    echo "uWSGI for cGit-ui appears to already be running?"
    exit 1
  fi

  echo "Starting uWSGI for cGit-ui server daemon..."
  if [ -x $BIN ]; then
    /bin/mkdir -p /run/uwsgi
    /bin/chown nginx:nginx /run/uwsgi
    /bin/chmod 0755 /run/uwsgi
    $BIN --thunder-lock --pidfile $PID --daemonize /var/log/cgit-ui-uwsgi.log --ini $CONFDIR/$CONF.ini
  fi
}

uwsgi_stop() {
  echo "Shutdown uWSGI for cGit-ui gracefully..."
  /bin/kill -INT $(cat $PID)
  /bin/rm -f $PID
}

uwsgi_reload() {
  echo "Reloading uWSGI for cGit-ui configuration..."
  kill -HUP $(cat $PID)
}

uwsgi_restart() {
  uwsgi_stop
  sleep 3
  uwsgi_start
}

case "$1" in
  start)
    uwsgi_start
    ;;
  stop)
    uwsgi_stop
    ;;
  reload)
    uwsgi_reload
    ;;
  restart)
    uwsgi_restart
    ;;
  *)
  echo "usage: `basename $0` {start|stop|reload|restart}"
esac

To run this daemon on systems with BSD-like initialization such as Slackware we have to add the following lines to the /etc/rc.d/rc.M and /etc/rc.d/rc.6 scripts correspondingly.

/etc/rc.d/rc.M:

# Start uWSGI for cGit-ui server:
if [ -x /etc/rc.d/rc.cgit-ui-uwsgi ]; then
  /etc/rc.d/rc.cgit-ui-uwsgi start
fi

/etc/rc.d/rc.6:

# Stop uWSGI for cGit-ui server:
if [ -x /etc/rc.d/rc.cgit-ui-uwsgi ]; then
  /etc/rc.d/rc.cgit-ui-uwsgi stop
fi

Nginx

First of all, we have to add a virtual server to the main Nginx config file:

/etc/nginx/nginx.conf:

    include /etc/nginx/vhosts/cgit.example.org.conf;

The following configuration used uWsgi and will serve cGit-UI on a subdomain like cgit.example.org:

/etc/nginx/vhosts/cgit.example.org.conf:

#
# cGit server:
#

    server {
        listen 80;
        server_name cgit.example.org;
        return 301 https://cgit.example.org$request_uri;
    }

    server {
        listen 443 ssl;
        server_name cgit.example.org;
        root /var/www/htdocs/cgit;

        charset UTF-8;

        #
        # see:
        #   https://developer.mozilla.org/en-US/docs/Web/Security/HTTP_strict_transport_security ,
        #   https://raymii.org/s/tutorials/HTTP_Strict_Transport_Security_for_Apache_NGINX_and_Lighttpd.html
        #
        # see also: http://classically.me/blogs/how-clear-hsts-settings-major-browsers
        # and do not include includeSubdomains; parameter into line:
        #
        add_header Strict-Transport-Security "max-age=63072000; preload";

        error_log /var/log/nginx/cgit.example.org-error.log;
        access_log /var/log/nginx/cgit.example.org-access.log;

        keepalive_timeout        60;
        ssl_certificate          /etc/letsencrypt/live/cgit.example.org/fullchain.pem;
        ssl_certificate_key      /etc/letsencrypt/live/cgit.example.org/privkey.pem;
        ssl_trusted_certificate  /etc/letsencrypt/live/cgit.example.org/chain.pem;
        ssl_protocols            SSLv3 TLSv1 TLSv1.1 TLSv1.2;
        ssl_ciphers              "RC4:HIGH:!aNULL:!MD5:!kEDH";

        gzip on;
        gzip_disable "msie6";
        gzip_comp_level 6;
        gzip_min_length 1100;
        gzip_buffers 16 8k;
        gzip_proxied any;
        gzip_types text/plain text/css text/js text/xml text/javascript
                   image/svg+xml image/gif image/jpeg image/png
                   application/json application/x-javascript application/xml application/xml+rss application/javascript
                   font/truetype font/opentype application/font-woff application/font-woff2
                   application/x-font-ttf application/x-font-opentype application/vnd.ms-fontobject application/font-sfnt;

        #
        # Serve static content with nginx
        #

        #
        # Rewrite rules for versioning CSS + JS thtouh filemtime directive
        #
        location ~* ^.+.(css|js)$ {
            rewrite ^(.+).(d+).(css|js)$ $1.$3 last;

            expires 31536000s;

            access_log off;
            log_not_found off;

            add_header Pragma public;
            add_header Cache-Control "max-age=31536000, public";
        }

        #
        # Caching of static files
        #
        location ~* .(asf|asx|wax|wmv|wmx|avi|bmp|class|divx|doc|docx|eot|exe|gif|gz|gzip|ico|jpg|jpeg|jpe|mdb|mid|midi|mov|qt|mp3|m4a|mp4|m4v|mpeg|mpg|mpe|mpp|odb|odc|odf|odg|odp|ods|odt|ogg|ogv|otf|pdf|png|pot|pps|ppt|pptx|ra|ram|svg|svgz|swf|tar|t?gz|tif|tiff|ttf|wav|webm|wma|woff|wri|xla|xls|xlsx|xlt|xlw|zip)$ {
            expires 31536000s;

            access_log off;
            log_not_found off;

            add_header Pragma public;
            add_header Cache-Control "max-age=31536000, public";
        }

        location ~* ^.+(favicon.ico|robots.txt) {
            root /var/www/htdocs/cgit;
            expires 30d;
        }

        location = /robots.txt {
            allow all;
            log_not_found off;
            access_log off;
        }

        location / {
            try_files $uri @cgit-ui;
        }

        location @cgit-ui {
            gzip off;
            include uwsgi_params;
            uwsgi_modifier1 9;
            uwsgi_pass unix:/run/uwsgi/cgit-ui.sock;
        }
    }

Configuring Git Repositories

A detailed description of the configuration file format can be found in the cgit-ui.rc(5) manual page:

man 5 cgit-ui.rc

Working Example

As an example, we will give a working configuration file in which the pkgtools.git repository is presented.

git-utc-offset = +0300;

clone-prefix-readonly = 'git://radix.pro';
clone-prefix          = 'git://git@radix.pro:pub';

trunk    = 'master';

snapshots = 'tar.xz';

css = '/.cgit/css/cgit.css';
logo = '/.cgit/pixmaps/cgit-banner-280x280.png';
logo-alt = "Radix.pro";
logo-link = "https://radix.pro";
main-menu-logo = '/.cgit/pixmaps/logo/git-logo-white-256x256.svg';
favicon-path = '/.cgit/pixmaps/favicon';
syntax-highlight-css = '_cgit.css';
header = '/.cgit/html/header.html';
footer = '/.cgit/html/footer.html';
page-size = 200;

owner = "Andrey V.Kosteltsev";
author = "Andrey V.Kosteltsev";
title = "Radix.pro Git Repositories";
description = "Git repositories hosted at radix.pro (St.-Petersburg)";
keywords = "cGit repositories cgit-ui web web-ui user interface Git";
copyright = "© Andrey V. Kosteltsev, 2019 – 2020.";
copyright-notice = "Where any material of this site is being reproduced, published or issued to others the reference to the source is obligatory.";

home-page = "https://radix.pro/";

section "Tools" {
  repo 'pkgtools.git' {
    owner = "Andrey V.Kosteltsev";
    title = "Package Tools Utilities";
    description = "Pkgtools – is a set of utilities to create, install, remove and update packages";
    home-page = "https://radix.pro/";
    git-root = '/u3/scm/git';
    clone-prefix-readonly = 'git://git@radix.pro:git';
    clone-prefix          = 'git://git@radix.pro:git';
  }
}

See Also

     README, cscmd(8), cgit-ui.rc(5)

Enjoy.