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-интерфейса так, как ему будет необходимо.
Artifeks
Простите, чисто из интереса, а зачем скрипты анализа трафика в гит репе? Ну и в целом по ux дизайну я бы добавил кнопку для копирования полного адреса для клонирования
rcl Автор
Например, если вы пишете документацию прямо в репе на Markdown и хотите понимать кто интересуется вашими проектами, то вы можете анализировать вашу аудиторию. Кроме того, размещая ваши репы на GitHub вы рискуете попасть в Gooogle-пузырь и ваши труды не достанутся общественности. Поэтому некоторые люди сами хотят продвигать свои проекты в сети.