2 a596b957 2022-07-14 tracey .\" Copyright (c) 2020 Stefan Sperling
4 a596b957 2022-07-14 tracey .\" Permission to use, copy, modify, and distribute this software for any
5 a596b957 2022-07-14 tracey .\" purpose with or without fee is hereby granted, provided that the above
6 a596b957 2022-07-14 tracey .\" copyright notice and this permission notice appear in all copies.
8 a596b957 2022-07-14 tracey .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
9 a596b957 2022-07-14 tracey .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
10 a596b957 2022-07-14 tracey .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
11 a596b957 2022-07-14 tracey .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
12 a596b957 2022-07-14 tracey .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
13 a596b957 2022-07-14 tracey .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
14 a596b957 2022-07-14 tracey .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
16 a596b957 2022-07-14 tracey .Dd $Mdocdate$
17 59975c69 2022-08-29 stsp .Dt GOTWEBD 8
21 59975c69 2022-08-29 stsp .Nd Game of Trees Git Fast-CGI repository server for web browsers
22 a596b957 2022-07-14 tracey .Sh SYNOPSIS
25 7de33ce2 2022-09-07 stsp .Op Fl D Ar macro=value
26 7de33ce2 2022-09-07 stsp .Op Fl f Ar file
27 a596b957 2022-07-14 tracey .Sh DESCRIPTION
29 59975c69 2022-08-29 stsp is a Fast-CGI server program which can display the contents of Git
30 59975c69 2022-08-29 stsp repositories via a web browser.
31 a596b957 2022-07-14 tracey The program has been designed to work out of the box with
33 a596b957 2022-07-14 tracey .Xr httpd 8
37 7de33ce2 2022-09-07 stsp provides the following options:
38 7de33ce2 2022-09-07 stsp .Bl -tag -width tenletters
40 7de33ce2 2022-09-07 stsp Do not daemonize and log to stderr.
41 7de33ce2 2022-09-07 stsp .It Fl D Ar macro=value
42 7de33ce2 2022-09-07 stsp Override the value of a macro used in the configuration file.
43 7de33ce2 2022-09-07 stsp .It Fl f Ar file
44 7de33ce2 2022-09-07 stsp Set the path to the configuration file.
45 7de33ce2 2022-09-07 stsp If not specified, the file
46 7de33ce2 2022-09-07 stsp .Pa /etc/gotwebd.conf
47 7de33ce2 2022-09-07 stsp will be used.
49 7de33ce2 2022-09-07 stsp Parse the configuration file, report errors if any, and exit.
51 7de33ce2 2022-09-07 stsp Verbose mode.
52 7de33ce2 2022-09-07 stsp Verbosity increases if this option is used multiple times.
57 a596b957 2022-07-14 tracey requires the following steps:
61 a596b957 2022-07-14 tracey .Xr httpd.conf 5
62 a596b957 2022-07-14 tracey configuration file must be adjusted to run
64 59975c69 2022-08-29 stsp as a Fast-CGI helper program.
66 a596b957 2022-07-14 tracey .Sx EXAMPLES
67 a596b957 2022-07-14 tracey section below contains an appropriate configuration file sample.
69 59975c69 2022-08-29 stsp httpd(8) must be enabled and started:
70 a596b957 2022-07-14 tracey .Bd -literal -offset indent
71 59975c69 2022-08-29 stsp # rcctl enable httpd
72 59975c69 2022-08-29 stsp # rcctl start httpd
75 a596b957 2022-07-14 tracey Optionally, the run-time behaviour of
77 a596b957 2022-07-14 tracey can be configured via the
78 59975c69 2022-08-29 stsp .Xr gotwebd.conf 5
79 a596b957 2022-07-14 tracey configuration file.
81 a596b957 2022-07-14 tracey Git repositories must be created at a suitable location inside the
82 a596b957 2022-07-14 tracey web server's
83 a596b957 2022-07-14 tracey .Xr chroot 2
84 a596b957 2022-07-14 tracey environment.
85 a596b957 2022-07-14 tracey These repositories should
87 e4556f5a 2022-08-30 stsp be writable by the user ID shared between
90 e4556f5a 2022-08-30 stsp .Xr httpd 8 .
91 a596b957 2022-07-14 tracey The default location for repositories published by
94 a596b957 2022-07-14 tracey .Pa /var/www/got/public .
96 a596b957 2022-07-14 tracey Git repositories served by
98 a596b957 2022-07-14 tracey should be kept up-to-date with a mechanism such as
99 a596b957 2022-07-14 tracey .Cm got fetch ,
100 a596b957 2022-07-14 tracey .Xr git-fetch 1 ,
102 a596b957 2022-07-14 tracey .Xr rsync 1 ,
103 a596b957 2022-07-14 tracey scheduled by
104 a596b957 2022-07-14 tracey .Xr cron 8 .
106 a596b957 2022-07-14 tracey .Sh FILES
107 a596b957 2022-07-14 tracey .Bl -tag -width /var/www/got/public/ -compact
108 7e8fc9b5 2022-09-07 stsp .It Pa /etc/gotwebd.conf
109 7e8fc9b5 2022-09-07 stsp Default location of the
110 7e8fc9b5 2022-09-07 stsp .Xr gotwebd.conf 5
111 7e8fc9b5 2022-09-07 stsp configuration file.
112 a596b957 2022-07-14 tracey .It Pa /var/www/got/public/
113 a596b957 2022-07-14 tracey Default location for Git repositories served by
115 a596b957 2022-07-14 tracey This location can be adjusted in the
116 59975c69 2022-08-29 stsp .Xr gotwebd.conf 5
117 a596b957 2022-07-14 tracey configuration file.
118 59975c69 2022-08-29 stsp .It Pa /var/www/bin/gotwebd/
119 a596b957 2022-07-14 tracey Directory containing statically linked
120 a596b957 2022-07-14 tracey .Xr got 1
121 a596b957 2022-07-14 tracey helper programs which are run by
123 a596b957 2022-07-14 tracey to read Git repositories.
124 59975c69 2022-08-29 stsp .It Pa /var/www/htdocs/gotwebd/
125 a596b957 2022-07-14 tracey Directory containing HTML, CSS, and image files used by
127 59975c69 2022-08-29 stsp .It Pa /tmp/
128 a596b957 2022-07-14 tracey Directory for temporary files created by
131 a596b957 2022-07-14 tracey .Sh EXAMPLES
132 41d6d08a 2022-09-07 stsp Example configuration for
133 41d6d08a 2022-09-07 stsp .Xr httpd.conf 5 :
134 a596b957 2022-07-14 tracey .Bd -literal -offset indent
135 a596b957 2022-07-14 tracey types { include "/usr/share/misc/mime.types" }
137 dbcc187b 2022-08-30 stsp # one gotwebd reachable at http://gotweb1.example.com/
138 dbcc187b 2022-08-30 stsp server "gotweb1.example.com" {
139 dbcc187b 2022-08-30 stsp listen on * port 80
140 dbcc187b 2022-08-30 stsp root "/htdocs/gotwebd"
141 dbcc187b 2022-08-30 stsp location "/" {
142 dbcc187b 2022-08-30 stsp fastcgi socket tcp localhost 9000
146 dbcc187b 2022-08-30 stsp # hosting multiple gotwebd instances on the same HTTP server:
147 dbcc187b 2022-08-30 stsp # http://gotweb2.example.com/gotwebd-unix/
148 dbcc187b 2022-08-30 stsp # http://gotweb2.example.com/gotwebd-tcp/
149 dbcc187b 2022-08-30 stsp server "gotweb2.example.com" {
150 dbcc187b 2022-08-30 stsp listen on * port 80
151 dbcc187b 2022-08-30 stsp location "/gotwebd-unix/" {
152 59975c69 2022-08-29 stsp fastcgi socket "/run/gotweb.sock"
154 dbcc187b 2022-08-30 stsp location "/gotwebd-unix/*" {
155 dbcc187b 2022-08-30 stsp root "/htdocs/gotwebd"
156 dbcc187b 2022-08-30 stsp request strip 1
158 dbcc187b 2022-08-30 stsp location "/gotwebd-tcp/" {
159 59975c69 2022-08-29 stsp fastcgi socket tcp 127.0.0.1 9000
161 dbcc187b 2022-08-30 stsp location "/gotwebd-tcp/*" {
162 dbcc187b 2022-08-30 stsp root "/htdocs/gotwebd"
163 dbcc187b 2022-08-30 stsp request strip 1
167 a596b957 2022-07-14 tracey .Sh SEE ALSO
168 a596b957 2022-07-14 tracey .Xr got 1 ,
169 a596b957 2022-07-14 tracey .Xr git-repository 5 ,
170 59975c69 2022-08-29 stsp .Xr gotwebd.conf 5 ,
171 41d6d08a 2022-09-07 stsp .Xr http.conf 5 ,
172 59975c69 2022-08-29 stsp .Xr httpd 8
173 a596b957 2022-07-14 tracey .Sh AUTHORS
174 59975c69 2022-08-29 stsp .An Omar Polo Aq Mt op@openbsd.org
175 a596b957 2022-07-14 tracey .An Stefan Sperling Aq Mt stsp@openbsd.org
176 59975c69 2022-08-29 stsp .An Tracey Emery Aq Mt tracey@traceyemery.net