From bfc1508d26c89c9a36d2d9a827fe2c4ed128884d Mon Sep 17 00:00:00 2001 From: kx Date: Fri, 24 Mar 2023 03:55:33 +0300 Subject: Version 0.1.4 --- README.md | 390 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 390 insertions(+) create mode 100644 README.md (limited to 'README.md') 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 + +© Andrey V. Kosteltsev, 2019 – 2020.
+Code and documentation released under [the **Radix.pro** License](https://csvn.radix.pro/csvn-ui/trunk/LICENSE). -- cgit v1.2.3