cGit-ui — это web-интерфейс для Git-репозиториев, основу которого предстваляет CGI-скрипт написанный на языке С.


cGit-ui поддерживает Markdown-файлы, которые обрабатываются на стороне сервера с помощью библиотеки md4c, зарекомендовавшей себя в проекте KDE Plasma. cGit-ui предоставляет возможность размещения кодов верификации сайта, а также скриптов от таких систем как Google Analytics и Yandex.Metrika для анализа трафика.


Пользователи cGit-ui получают широкие возможности для настройки как внешнего вида, так и функциональности собственного сайта, на котором они представляют свои репозитории. Кроме того, cGit-ui позволяет создавать и размещать на сайте, так называемые Donation-диалоги для приема пожертвований в пользу тех или иных проектов.


Внешний вид и функциональность сайтов, построенных на cGit-ui, можно рассмотреть на примере где, в том числе, представлены достаточно большие Git-репозитории, что позволяет примерно оценить скорость работы интерфейса. Рассматривать сайт в работе лучше начинать со смартфона, а затем переходить на более широкие экраны.


С момента выхода интерфейса к Subversion-репозиториям произошел ряд изменений в структуре пакетов, необходимых для установки. Так, например, cScm-демон, который служит для разбора конфигурационных файлов, выделен в отдельный пакет.


Поэтому в данной статье дается более развернутое описание cGit-ui.


Установку и настройку cGit-ui необходимо начинать с инсталляции cScm-демона, который одновременно может поддерживать как cSvn-ui, так и интерфейс к Git-репозиториям.


Инсталляция cScm-демона


cScm-демон служит для того, чтобы не нагружать лишней работой, связаной с разбором конфирурационных файлов, основные CGI-скрипты cSvn-ui и cGit-ui. cScm-демон преобразует список репозиториев /etc/cgit-ui.rc(5) в двоичный формат, который поступает на вход cGit-ui CGI-скрипта через разделяемую память. Таким образом CGI-скрипт не тратит время на синтаксический анализ списка репозиториев.


Исходный пакет cScm можно получить двумя способами: загрузить с FTP-сервера или с помощью Subversion:


svn checkout svn://radix.pro/cscm/tags/cscm-0.1.3 cscm-0.1.3

Если использован второй способ, то перед сборкой пакета необходимо приготовить исходные тексты для их последующего конфигурирования. Для этого нужно воспользоваться скриптом bootstrap:


cd cscm-0.1.3
./bootstarp

который установит Autotools средства, соберет коллекцию aclocal.m4 и создаст configure скрипт.


Далее как обычно для пакетов использующих Autotools:


./configure --prefix=/usr             --sysconfdir=/etc             --with-controldir=/etc/rc.d             --with-logrotatedir=/etc/logrotate.d             --with-homepath=/var/lib             --with-logdir=/var/log             --with-piddir=/var/run
make
make install

Для запуска cScm-демона надо сделать следующие файлы исполняемыми:


chmod a+x /etc/rc.d/rc.csvnd
chmod a+x /etc/rc.d/rc.cgitd

Если же вы хотите запускать cscmd(8) демоны при старте системы, которая имеет BSD-like инициализацию, такой как Slackware, необходимо в скрипты /etc/rc.d/rc.M и /etc/rc.d/rc.6 добавить следующие строки, соответственно:


/etc/rc.d/rc.M:
# Start cSvn SCM daemon:
if [ -x /etc/rc.d/rc.csvnd ] ; then
  /etc/rc.d/rc.csvnd start
fi

# Start cGit SCM daemon:
if [ -x /etc/rc.d/rc.cgitd ] ; then
  /etc/rc.d/rc.cgitd start
fi

/etc/rc.d/rc.6:
# Stop cSvn SCM daemon:
if [ -x /etc/rc.d/rc.csvnd ] ; then
  /etc/rc.d/rc.csvnd stop
fi

# Stop cGit SCM daemon:
if [ -x /etc/rc.d/rc.cgitd ] ; then
  /etc/rc.d/rc.cgitd stop
fi

Для систем использующих systemd, необходимо установить файлы, подобные следующим:


/etc/systemd/system/csvnd.service:
[Unit]
Description=The cSvn daemon
After=network.target

[Service]
PIDFile=/var/run/csvnd.pid
ExecStart=/usr/sbin/cscmd --daemonize --inotify --scm=svn --pid=/var/run/csvnd.pid --log=/var/log/csvnd.log --config=/etc/csvn-ui.rc
ExecReload=/bin/kill -s HUP $MAINPID
ExecStop=/bin/kill -s TERM $MAINPID

[Install]
WantedBy=multi-user.target

/etc/systemd/system/cgitd.service:
[Unit]
Description=The cGit daemon
After=network.target

[Service]
PIDFile=/var/run/cgitd.pid
ExecStart=/usr/sbin/cscmd --daemonize --inotify --scm=git --pid=/var/run/cgitd.pid --log=/var/log/cgitd.log --config=/etc/cgit-ui.rc
ExecReload=/bin/kill -s HUP $MAINPID
ExecStop=/bin/kill -s TERM $MAINPID

[Install]
WantedBy=multi-user.target

Прежде чем запускать cscmd-демон надо создать конфигурационный файл с описанием репозиториев, например, /etc/cgit-ui.rc(5). После запуска демона в log-файле /var/log/cgitd.log можно будет видеть текущее состояние работы или описание ошибок, которые допущены в файле конфигурации.


Обратите внимание на опцию --inotify. Данная опция позволяет не посылать демону сигнал о том что надо перечитать конфигурационный файл после каждого редактирования настроек списка репозиториев. Демон самостоятельно будет отслеживать изменения в файле /etc/cgit-ui.rc(5).


Граматика файлов /etc/cgit-ui.rc(5) и /etc/csvn-ui.rc(5) элементарна. Посмотреть не нее можно в файле parse.y. Структура бинарного файла списка репозиториев описана в файле bcf.h.


Бинарные пакеты


Еще нет Linux-дистрибутивов, имеющих в пакетной базе программы cSvn-ui и cGit-ui. Однако пользователи могут самостоятельно собрать нужные им пакеты по инструкциям в каталоге doc/build-packages. Здесь есть наброски spec-файла для систем, использующих RPM, файл сборки пакета для ArchLinux, а также скрипт для Slackware.


Дополнительную информацию о cscmd(8) можно получить на странице руководства:


man 8 cscmd

Подготовка исходного пакета cGit-ui


Исходный пакет cGit-ui так же можно получить двумя способами: загрузить с FTP-сервера или с помощью Subversion:


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

Второй способ, как всегда, подразумевает использование скрипта bootstrap для подготовки к сборке:


cd cgit-ui-0.1.5
./bootstarp

Требуемые пакеты


cGit-ui CGI-скрипт зависит от следующих библиотек: libpcre2, libmd4c, libmd4c-html, libmagic, libgit2.


Разумеется, для использования cGit-ui, в системе должен быть установлен web-сервер и какой-либо сервер приложений. Далее мы будем рассматривать связку Nginx + uWsgi, однако на ряду с uWsgi, пользователи могут выбрать CGI или FastCGI, которые поддерживаются сервером Nginx.


Инсталляция cGit-ui


Здесь необходимо только выбрать каталог, в который будут установлены, как сам CGI-скрипт, так и все необходимые компоненты web-сайта пользователя:


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

После установки пакета необходимо отдать права на каталог пользователю, от имени которого работает web-сервер:


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

uWsgi


Поскольку, на стадии конфигурирования исходых текстов, мы выбрали каталог установки --with-scriptdir=/var/www/htdocs/cgit, далее все настройки будут производиться относительно именно этого каталога. Конфигурационный файл сервера приложений /etc/uwsgi/cgit-ui.ini должен выглядеть следующим образом:


/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

Здесь cgi = /var/www/htdocs/cgit/cgit-ui.cgi представляет полное имя CGI-скрипта cGit-ui.


Для запуска uWSGI-демона можно воспользоваться следующим скриптом:


/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

Если же необходимо запускать uWSGI-демон во время загрузки системы c BSD-like инициализацией, такой, например, как Slackware, то в файлы /etc/rc.d/rc.M, /etc/rc.d/rc.6 нужно добавить следующие строки:


/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


Прежде всего, необходимо включить новый виртуальный сервер в конфигурационный файл Nginx:


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

Следующая конфигурация сервера подразумевает использование uWsgi и скрипта cGit-UI на поддомене 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;


        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;
        }
    }

Создание списка репозиториев


Детальные инструкции, описывающие формат файла cgit-ui.rc(5) можно найти на странице руководства:


man 5 cgit-ui.rc

Рабочий Пример


Следующий конфигурационный файл содержит все необходимые, для работы сервера, настройки, одну секцию из списка репозиториев, именуемую «Tools» и содержащую описание Git-репозитория pkgtools.git.


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';
  }
}

Здесь можно видеть, что cGit-ui CGI-скрипт использует HTML-шаблоны заголовка и подножия страниц, в котрые подставляет значения некоторых переменных, определенных в конфигурационном файле cgit-ui.rc(5).


Такой подход дает возможность пользователю полностью контролировать как внешний вид интерфейса, так и его поведение исходя из собственных предпочтений:


Все необходимые файлы для работы на стороне web-клиента находятся в каталоге /var/www/htdocs/cgit/.cgit/. Редактируя файл /.cgit/html/header.html и меняя значения переменных в файле /etc/cgit-ui.rc, пользователь может сменить favicon.ico, поменять тему подсветки синтаксиса, выбрать изображения для собственных репозиториев, задать ключевые слова для поисковых систем, а также выполнить множество других настроек собственного сервера, представляющего Git-репозиториии.


Внешний вид интерфейса определяется единственным CSS-файлом и поэтому, пользователь может поменять тему web-интерфейса так, как ему будет необходимо.


Дополнительная информация


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