GOTWEBD(8)

NAME

gotwebd — Game of Trees FastCGI server for web browsers

SYNOPSIS

gotwebd [-dnv] [-D macro=value] [-f file]

DESCRIPTION

gotwebd is a FastCGI server program which can display the contents of Git repositories via a web browser. The program has been designed to work out of the box with the httpd(8) web server.

gotwebd provides the following options:

-D macro=value: Define macro to be set to value. Overrides the definition of macro in the configuration file.
-d: Do not daemonize. Send log output to stderr.
-f file: Set the path to the configuration file. If not specified, the file /etc/gotwebd.conf will be used.
-n: Parse the configuration file, report errors if any, and exit.
-v: Verbose mode. Verbosity increases if this option is used multiple times.

Enabling gotwebd requires the following steps:

The httpd.conf(5) configuration file must be adjusted to run gotwebd as a FastCGI helper program. The EXAMPLES section below contains an appropriate configuration file sample.

httpd(8) must be enabled and started:

  # rcctl enable httpd
  # rcctl start httpd

Optionally, the run-time behaviour of gotwebd can be configured via the gotwebd.conf(5) configuration file.
Git repositories must be created. These repositories may reside anywhere in the filesystem and must be readable, but should not be writable, by the user gotwebd runs as. The default location for repositories published by gotwebd is /var/www/got/public.
If the Git repositories served by gotwebd do not receive changes from committers directly, they need to be kept up-to-date with a mechanism such as got fetch, git-fetch(1), or rsync(1), scheduled by cron(8).

FILES

/etc/gotwebd.conf: Default location of the gotwebd.conf(5) configuration file.
/var/www/got/public/: Default location for Git repositories served by gotwebd. This location can be adjusted in the gotwebd.conf(5) configuration file.
/var/www/bin/gotwebd/: Directory containing statically linked got(1) helper programs which are run by gotwebd to read Git repositories.
/var/www/htdocs/gotwebd/: Directory containing HTML, CSS, and image files used by gotwebd.
/var/www/run/gotweb.sock: Default location for the gotwebd listening socket.
/var/run/gotweb-login.sock: Default location for the gotwebd login socket.
/var/run/gotwebd.sock: Default location for the gotwebd control socket. gotwebctl(8) can be used to send commands to gotwebd via this socket.
/tmp/: Directory for temporary files created by gotwebd.

EXAMPLES

Example configuration for httpd.conf(5) which forwards all requests to gotwebd:

types { include "/usr/share/misc/mime.types" }

server "example.com" {
	listen on * port 80
	fastcgi socket "/run/gotweb.sock"
}

The following httpd.conf(5) example makes multiple gotwebd instances reachable via the same HTTP server under different URL path prefixes, with the first reached via the default Unix-domain socket, and the second configured to listen on localhost port 9000:

server "example.com" {
	listen on * port 80

	location "/gotwebd-unix/*" {
		fastcgi socket "/run/gotweb.sock"
	}

	location "/gotwebd-tcp/*" {
		fastcgi socket tcp localhost 9000
	}

	# Redirect requests which lack a trailing slash:

	location "/gotwebd-unix" {
		block return 302 \
			"$REQUEST_SCHEME://$HTTP_HOST$REQUEST_URI/"
	}

	location "/gotwebd-tcp" {
		block return 302 \
			"$REQUEST_SCHEME://$HTTP_HOST$REQUEST_URI/"
	}
}

When requests do not arrive at the root URL path “/”, the URL path prefix also needs to be set in the gotwebd.conf(5) file corresponding to each instance of gotwebd. Following on from the previous example:

gotwebd.conf(5) for the Unix-domain socket instance of gotwebd:

listen on socket "/var/www/run/gotweb.sock"
server "example.com" {
	gotweb_url_root "/gotwebd-unix"
}

gotwebd.conf(5) for the TCP instance of gotwebd:

listen on localhost port 9000
server "example.com" {
	gotweb_url_root "/gotwebd-tcp"
}

AUTHORS