From 05d292b208dfe01324826b4c87bbc4da3389a0d5 Mon Sep 17 00:00:00 2001 From: kx Date: Fri, 24 Mar 2023 03:51:10 +0300 Subject: Version 0.1.7 --- README.md | 372 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 372 insertions(+) create mode 100644 README.md (limited to 'README.md') diff --git a/README.md b/README.md new file mode 100644 index 0000000..a82b2ce --- /dev/null +++ b/README.md @@ -0,0 +1,372 @@ + +# cGit-UI for Git repositories + +**cGit-UI** – is a web interface for Git Repositories. **cGit** CGI script is writen in **C** +and therefore it's fast enough. + + +## Table of Contents + +* [Reqired packages](#required-packages) +* [Installation](#installation) + * [Download Sources](#download-sources) + * [Configuring Sources](#configuring-sources) + * [Post Install](#post-install) +* [uWsgi Configuration](#uwsgi) +* [Nginx Configuration](#nginx) +* [Configuring Git Repositories](#configuring-git-repositories) +* [See Also](#see-also) +* [Copyright and License](#copyright-and-license) + + +## Required packages + +**cGit-ui** depends of following libraries: [libpcre2-8](https://www.pcre.org/), +[librt](https://www.gnu.org/software/libc/), [libm](https://www.gnu.org/software/libc/), +[libmd4c](https://github.com/mity/md4c/), [libmd4c-html](https://github.com/mity/md4c/), +[libmagic](http://darwinsys.com/file/), and [libgit2](https://libgit2.org/). + +Also **cGit-ui** depends on the **cScm** package. Therefore, before installing **cGit-ui**, +you have to install and configure [**cScm Configuration Daemon**](https://csvn.radix.pro/cscm/trunk/README.md). + +To use **cGit-ui** a web server must be installed and configured on the system. We recommend +the [Nginx](https://nginx.org/en/) with [uWsgi](https://uwsgi-docs.readthedocs.io/en/latest/) +application server. Of course [Git](https://git-scm.com/) SCM system should be installed too. + + +## Installation + +To obtain sources we have to checkout its from SVN repository: + +```Bash +svn checkout svn://radix.pro/cgit-ui/tags/cgit-ui-0.1.3 cgit-ui-0.1.3 +``` +and run the bootstrap script: + +```Bash +cd cgit-ui-0.1.3 +./bootstrap +``` +Also **cGit-ui** source packages are available for download on the +[Radix.pro FTP-server](https://ftp.radix.pro/pub/cgit-ui/). + + +#### Bootstrap Script + +The *bootstrap* script especialy created for *Autotools* install automation. To install +*Autotools* into sourse directory on build machine (i.e. when **build** == **host**) the *bootstrap* +script can be run without arguments. + +```Bash +./bootstrap +``` + +I 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: + +```Bash +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 + +```Bash +./configure --prefix=/usr \ + --with-scriptdir=/var/www/htdocs/cgit +``` + + +#### Install on the Build Machine + +```Bash +make +make install +``` + + +#### Cross Compilation Example + +```Bash +#!/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`: + +```Bash +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: + +```Bash +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: + +```Bash +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:** + +```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** frontend we can make use following start/stop script: + +**/ets/rc.d/rc.cgit-ui-uwsgi:** + +```Bash +#!/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 following lines to the */etc/rc.d/rc.M* and */etc/rc.d/rc.6* scripts +correspondingly. + +**/etc/rc.d/rc.M:** + +```Bash +# 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:** + +```Bash +# 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 virtual server to the main **Nginx** config file: + +**/etc/nginx/nginx.conf:** + +```Nginx + 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:** + +```Nginx +# +# 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; + } + } +``` + + +## Configuring Git Repositories + +A detailed description of the configuration file format can be found in the +[**cgit-ui.rc(5)**](https://csvn.radix.pro/cgit-ui/trunk/doc/cgit-ui.rc.5.md) manual page: + +```Bash +man 5 cgit-ui.rc +``` + + +## See Also + +> [**cscmd(8)**](https://csvn.radix.pro/cscm/trunk/doc/cscmd.8.md),  +> [**cgit-ui.rc(5)**](https://csvn.radix.pro/cgit-ui/trunk/doc/cgit-ui.rc.5.md) + + +## Copyright and License + +© Andrey V. Kosteltsev, 2019 – 2022.
+Code and documentation released under [the **Radix.pro** License](https://csvn.radix.pro/cgit-ui/trunk/LICENSE). -- cgit v1.2.3