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 httpd.conf:
133 .Bd -literal -offset indent
134   types { include "/usr/share/misc/mime.types" }
135 
136   # one gotwebd reachable at http://gotweb1.example.com/
137   server "gotweb1.example.com" {
138         listen on * port 80
139         root "/htdocs/gotwebd"
140         location "/" {
141               fastcgi socket tcp localhost 9000
142         }
143   }
144 
145   # hosting multiple gotwebd instances on the same HTTP server:
146   # http://gotweb2.example.com/gotwebd-unix/
147   # http://gotweb2.example.com/gotwebd-tcp/
148   server "gotweb2.example.com" {
149         listen on * port 80
150         location "/gotwebd-unix/" {
151               fastcgi socket "/run/gotweb.sock"
152         }
153         location "/gotwebd-unix/*" {
154                root "/htdocs/gotwebd"
155                request strip 1
156         }
157         location "/gotwebd-tcp/" {
158               fastcgi socket tcp 127.0.0.1 9000
159         }
160         location "/gotwebd-tcp/*" {
161                root "/htdocs/gotwebd"
162                request strip 1
163         }
164   }
165 .Ed
166 .Sh SEE ALSO
167 .Xr got 1 ,
168 .Xr git-repository 5 ,
169 .Xr gotwebd.conf 5 ,
170 .Xr httpd 8
171 .Sh AUTHORS
172 .An Omar Polo Aq Mt op@openbsd.org
173 .An Stefan Sperling Aq Mt stsp@openbsd.org
174 .An Tracey Emery Aq Mt tracey@traceyemery.net