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