Version 0.1.4

1 files changed, 390 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..5a3ab54
--- /dev/null
+++ b/README.md
@@ -0,0 +1,390 @@
+
+# cSvn-UI for SVN Repositories
+
+**cSvn-UI** – is a web interface for Subversion (SVN) Repositories. **cSvn** CGI script is writen in **C**
+and therefore it's fast enough.
+
+
+## Table of Contents
+
+* [Reqired packages](#reqired-packages)
+* [Installation](#installation)
+    * [Bootstrap Script](#bootstrap-script)
+    * [Configuring Sources](#configuring-sources)
+    * [Post Install](#post-install)
+* [uWsgi Configuration](#uwsgi)
+* [Nginx Configuration](#nginx)
+* [Configuring SVN Repositories](#configuring-svn-repositories)
+* [See Also](#see-also)
+* [Copyright and License](#copyright-and-license)
+
+
+## Reqired packages
+
+**cSvn-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 [libxml2](http://www.xmlsoft.org/).
+
+From the moment when the **cSvn** package was split into two, so as do not produce
+unnecessary entities, **cSvn-ui** depends on the **cScm** package. Therefore, before
+installing **cSvn-ui**, you have to install and configure
+[**cScm Configuration Daemon**](https://csvn.radix.pro/cscm/trunk/README.md).
+
+To use **cSvn-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 [Apache Subversion](https://subversion.apache.org/) SCM system
+should be installed too.
+
+
+## Installation
+
+To obtain sources we have to checkout its from SVN repository:
+
+```Bash
+svn checkout svn://radix.pro/csvn-ui/tags/csvn-ui-0.1.3 csvn-ui-0.1.3
+```
+and run the bootstrap script:
+
+```Bash
+cd csvn-ui-0.1.3
+./bootstrap
+```
+Also **cSvn-ui** source packages are available for download on the
+[Radix.pro FTP-server](https://ftp.radix.pro/pub/csvn-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/csvn
+```
+
+
+#### 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/csvn
+
+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 **cSvn-ui CGI script** was installed:
+
+```Bash
+chown -R nginx:nginx /var/www/htdocs/csvn
+```
+
+
+## uWsgi
+
+Since we used the *--with-scriptdir=/var/www/htdocs/csvn* option on configuring stage,
+the **cSvn-ui** CGI script installed in the */var/www/htdocs/csvn/* directory. In this case,
+the */etc/uwsgi/csvn-ui.ini* file should look like this:
+
+**/etc/uwsgi/csvn-ui.ini:**
+
+```ini
+[uwsgi]
+master          = true
+plugins         = cgi
+socket          = /run/uwsgi/%n.sock
+uid             = nginx
+gid             = nginx
+procname-master = uwsgi csvn-ui
+processes       = 1
+threads         = 2
+cgi             = /var/www/htdocs/csvn/csvn-ui.cgi
+```
+
+Where */var/www/htdocs/csvn/csvn-ui.cgi* is the full name of installed **cSvn-ui** CGI script.
+
+To run the **uWSGI** daemon for **cSvn-ui** backend we can make use following start/stop script:
+
+**/ets/rc.d/rc.csvn-ui-uwsgi:**
+
+```Bash
+#!/bin/sh
+#
+# uWSGI daemon control script.
+#
+
+CONF=csvn-ui
+BIN=/usr/bin/uwsgi
+CONFDIR=/etc/uwsgi
+PID=/var/run/$CONF-uwsgi.pid
+
+uwsgi_start() {
+  # Sanity checks.
+  if [ ! -r $CONFDIR/csvn-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 cSvn-ui appears to already be running?"
+    exit 1
+  fi
+
+  echo "Starting uWSGI for cSvn-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/csvn-ui-uwsgi.log --ini $CONFDIR/$CONF.ini
+  fi
+}
+
+uwsgi_stop() {
+  echo "Shutdown uWSGI for cSvn-ui gracefully..."
+  /bin/kill -INT $(cat $PID)
+  /bin/rm -f $PID
+}
+
+uwsgi_reload() {
+  echo "Reloading uWSGI for cSvn-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 cSvn-ui server:
+if [ -x /etc/rc.d/rc.csvn-ui-uwsgi ]; then
+  /etc/rc.d/rc.csvn-ui-uwsgi start
+fi
+```
+
+**/etc/rc.d/rc.6:**
+
+```Bash
+# Stop uWSGI for cSvn-ui server:
+if [ -x /etc/rc.d/rc.csvn-ui-uwsgi ]; then
+  /etc/rc.d/rc.csvn-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/csvn.example.org.conf;
+```
+
+The following configuration used **uWsgi** and will serve **cSvn-ui** on a subdomain
+like *csvn.example.org*:
+
+**/etc/nginx/vhosts/csvn.example.org.conf:**
+
+```Nginx
+#
+# cSvn server:
+#
+
+    server {
+        listen 80;
+        server_name csvn.example.org;
+        return 301 https://csvn.example.org$request_uri;
+    }
+
+    server {
+        listen 443 ssl;
+        server_name csvn.example.org;
+        root /var/www/htdocs/csvn;
+
+        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/csvn.example.org-error.log;
+        access_log /var/log/nginx/csvn.example.org-access.log;
+
+        keepalive_timeout        60;
+        ssl_certificate          /etc/letsencrypt/live/csvn.example.org/fullchain.pem;
+        ssl_certificate_key      /etc/letsencrypt/live/csvn.example.org/privkey.pem;
+        ssl_trusted_certificate  /etc/letsencrypt/live/csvn.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/csvn;
+            expires 30d;
+        }
+
+        location = /robots.txt {
+            allow all;
+            log_not_found off;
+            access_log off;
+        }
+
+        location / {
+            try_files $uri @csvn-ui;
+        }
+
+        location @csvn-ui {
+            gzip off;
+            include uwsgi_params;
+            uwsgi_modifier1 9;
+            uwsgi_pass unix:/run/uwsgi/csvn-ui.sock;
+        }
+    }
+```
+
+
+## Configuring SVN Repositories
+
+A detailed description of the configuration file format can be found in the
+[**csvn-ui.rc(5)**](https://csvn.radix.pro/csvn-ui/trunk/doc/csvn-ui.rc.5.md) manual page:
+
+```Bash
+man 5 csvn-ui.rc
+```
+
+Here we will give an example of a description of the
+[Apache Subversion repository](https://svn.apache.org/viewvc/subversion/trunk/).
+Please note that the Apache server responds very slowly to HTTP requests.
+
+```dts
+/**************************
+  Apache's SVN repository:
+ */
+home-page = "https://svn.apache.org/";
+
+section "Subversion" {
+  repo 'subversion' {
+    owner = "Apache";
+    description = "Source repository of the Subversion.";
+    checkout-prefix-readonly = 'https://svn.apache.org/repos/asf';
+  }
+}
+```
+
+To access your own repositories, we recommend the **svn+ssh** protocol.
+
+
+## See Also
+
+> [**cscmd(8)**](https://csvn.radix.pro/cscm/trunk/doc/cscmd.8.md), 
+> [**csvn-ui.rc(5)**](https://csvn.radix.pro/csvn-ui/trunk/doc/csvn-ui.rc.5.md)
+
+
+## Copyright and License
+
+&#169; Andrey V. Kosteltsev, 2019 &#8211; 2020.<br/>
+Code and documentation released under [the **Radix.pro** License](https://csvn.radix.pro/csvn-ui/trunk/LICENSE).