commit 738b375608c4a414a6b663a335daaff281b7305b from: Stefan Sperling date: Tue Jan 28 18:14:30 2020 UTC add gotweb(8) man page and move README info there; discussed with tracey commit - 55e54fd34a05637a3eac2cf6503e62b689c172c1 commit + 738b375608c4a414a6b663a335daaff281b7305b blob - 1cb5da5f4b0849041fd3897a319584095998d935 blob + 50614083810a5bff0ea9c6caeb85872bb9a8495d --- README +++ README @@ -46,6 +46,7 @@ Man page files in the Got source tree can be viewed wi EXAMPLES in got.1 contains a quick-start guide for OpenBSD developers. + Game of Trees Web (Gotweb) is a CGI program which displays repository data and is designed to work with httpd(8) and slowcgi(8). @@ -59,32 +60,13 @@ This will create the following files: the CGI program /var/www/cgi-bin/gotweb/gotweb helper programs from the libexec directory in /var/www/cgi-bin/gotweb/libexec several template files in /var/www/cgi-bin/gw_tmpl/ - html, css, and image files in /var/www/htdocs/gotweb/gotweb/ + html, css, and image files in /var/www/htdocs/gotweb/ the directory /var/www/tmp/ man pages (only installed if building sources from a Got release tarball) -Example configuration for httpd.conf: +Documentation is available in manual pages: - types { include "/usr/share/misc/mime.types" } - server "localhost" { - listen on * port 80 - root "/htdocs/gotweb" - location "/cgi-bin/*" { - root "/" - fastcgi - } - location "/*" { - directory index "index.html" - } - } - -httpd(8) and slowcgi(8) should be enabled and started: - - # rcctl enable httpd slowcgi - # rcctl start httpd slowcgi - -Gotweb's run-time behaviour can be configured in the gotweb.conf file: - + $ man -l gotweb/gotweb.8 $ man -l gotweb/gotweb.conf.5 blob - 3a1ae060f78dfd753d5bbab1e8e897239ccf3bd0 blob + 392a7321fc2b1e67a5c0eaab2848f1ce17dcad7b --- gotweb/Makefile +++ gotweb/Makefile @@ -12,7 +12,7 @@ SRCS = gotweb.c parse.y blame.c commit_graph.c delta. privsep.c reference.c repository.c sha1.c worktree.c \ inflate.c buf.c rcsutil.c diff3.c lockfile.c \ deflate.c object_create.c delta_cache.c -MAN = ${PROG}.conf.5 +MAN = ${PROG}.conf.5 ${PROG}.8 CPPFLAGS += -I${.CURDIR}/../include -I${.CURDIR}/../lib -I${.CURDIR} \ -I${KCGIBASE}/include blob - /dev/null blob + c3edaa03dbab36f608f989beca79a6663064ddfe (mode 644) --- /dev/null +++ gotweb/gotweb.8 @@ -0,0 +1,150 @@ +.\" +.\" Copyright (c) 2020 Stefan Sperling +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd $Mdocdate$ +.Dt GOTWEB 8 +.Os +.Sh NAME +.Nm gotweb +.Nd Game of Trees Git repository server for web browsers +.Sh SYNOPSIS +.Nm +.Sh DESCRIPTION +.Nm +provides a simple web interface for read-only access to Git repositories, +allowing repository contents to be viewed with a web browser. +.Pp +.Nm +is a CGI program based on +.Xr got 1 +and +.Xr kcgi 3 +which is intended to run in a +.Xr chroot 2 +environment in +.Pa /var/www . +The program has been designed to work out of the box with +the +.Xr httpd 8 +web server in conjunction with +.Xr slowcgi 8 . +.Pp +Enabling +.Nm +requires the following steps: +.Bl -enum +.It +The +.Xr httpd.conf 5 +configuration file must be adjusted to run +.Nm +as a CGI program with +.Xr slowcgi 8 . +The +.Sx EXAMPLES +section below contains an appropriate configuration file sample. +.It +httpd(8) and slowcgi(8) must be enabled and started: +.Bd -literal -offset indent + # rcctl enable httpd slowcgi + # rcctl start httpd slowcgi +.Ed +.It +Optionally, the run-time behaviour of +.Nm +can be configured via the +.Xr gotweb.conf 5 +configuration file. +.It +Git repositories must be created at a suitable location inside the +web server's +.Xr chroot 2 +environment. +These repositories should +.Em not +be writable by the user ID of the +.Xr httpd 8 +server. +The default location for repositories published by +.Nm +is +.Pa /var/www/got/public . +.It +Git repositories served by +.Nm +should be kept up-to-date with a mechanism such as +.Xr git-fetch 1 +or +.Xr rsync 1 , +scheduled by +.Xr cron 8 . +.El +.Sh FILES +.Bl -tag -width /var/www/got/public/ -compact +.It Pa /var/www/got/public/ +Default location for Git repositories served by +.Nm . +This location can be adjusted in the +.Xr gotweb.conf 5 +configuration file. +.It Pa /var/www/cgi-bin/gotweb/gotweb +The +.Nm +CGI program, statically linked for use in a +.Xr chroot 2 +environment. +.It Pa /var/www/cgi-bin/gotweb/gw_tmpl/ +Directory for template files used by +.Nm . +.It Pa /var/www/cgi-bin/gotweb/libexec/ +Directory containing statically linked +.Xr got 1 +helper programs which are run by +.Nm +to read Git repositories. +.It Pa /var/www/htdocs/gotweb/ +Directory containing HTML, CSS, and image files used by +.Nm . +.It Pa /var/www/tmp/ +Directory for temporary files created by +.Nm . +.El +.Sh EXAMPLES +Example configuration for httpd.conf: +.Bd -literal -offset indent + + types { include "/usr/share/misc/mime.types" } + server "gotweb.example.com" { + listen on * port 80 + root "/htdocs/gotweb" + location "/cgi-bin/*" { + root "/" + fastcgi + } + location "/*" { + directory index "index.html" + } + } +.Ed +.Sh SEE ALSO +.Xr got 1 , +.Xr kcgi 3 , +.Xr git-repository 5 , +.Xr gotweb.conf 5 , +.Xr httpd 8 , +.Xr slowcgi 8 +.Sh AUTHORS +.An Tracey Emery Aq Mt tracey@traceyemery.net +.An Stefan Sperling Aq Mt stsp@openbsd.org