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 FastCGI repository server for web browsers
22 .Sh SYNOPSIS
23 .Nm
24 .Op Fl dnv
25 .Op Fl D Ar macro Ns = Ns Ar value
26 .Op Fl f Ar file
27 .Sh DESCRIPTION
28 .Nm
29 is a FastCGI 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 Ar macro Ns = Ns Ar value
40 Define
41 .Ar macro
42 to be set to
43 .Ar value .
44 Overrides the definition of
45 .Ar macro
46 in the configuration file.
47 .It Fl d
48 Do not daemonize.
49 Send log output to stderr.
50 .It Fl f Ar file
51 Set the path to the configuration file.
52 If not specified, the file
53 .Pa /etc/gotwebd.conf
54 will be used.
55 .It Fl n
56 Parse the configuration file, report errors if any, and exit.
57 .It Fl v
58 Verbose mode.
59 Verbosity increases if this option is used multiple times.
60 .El
61 .Pp
62 Enabling
63 .Nm
64 requires the following steps:
65 .Bl -enum
66 .It
67 The
68 .Xr httpd.conf 5
69 configuration file must be adjusted to run
70 .Nm
71 as a FastCGI helper program.
72 The
73 .Sx EXAMPLES
74 section below contains an appropriate configuration file sample.
75 .It
76 httpd(8) must be enabled and started:
77 .Bd -literal -offset indent
78   # rcctl enable httpd
79   # rcctl start httpd
80 .Ed
81 .It
82 Optionally, the run-time behaviour of
83 .Nm
84 can be configured via the
85 .Xr gotwebd.conf 5
86 configuration file.
87 .It
88 Git repositories must be created at a suitable location inside the
89 web server's
90 .Xr chroot 2
91 environment.
92 These repositories should
93 .Em not
94 be writable by the user ID shared between
95 .Nm
96 and
97 .Xr httpd 8 .
98 The default location for repositories published by
99 .Nm
100 is
101 .Pa /var/www/got/public .
102 .It
103 Git repositories served by
104 .Nm
105 should be kept up-to-date with a mechanism such as
106 .Cm got fetch ,
107 .Xr git-fetch 1 ,
108 or
109 .Xr rsync 1 ,
110 scheduled by
111 .Xr cron 8 .
112 .El
113 .Sh FILES
114 .Bl -tag -width /var/www/got/public/ -compact
115 .It Pa /etc/gotwebd.conf
116 Default location of the
117 .Xr gotwebd.conf 5
118 configuration file.
119 .It Pa /var/www/got/public/
120 Default location for Git repositories served by
121 .Nm .
122 This location can be adjusted in the
123 .Xr gotwebd.conf 5
124 configuration file.
125 .It Pa /var/www/bin/gotwebd/
126 Directory containing statically linked
127 .Xr got 1
128 helper programs which are run by
129 .Nm
130 to read Git repositories.
131 .It Pa /var/www/htdocs/gotwebd/
132 Directory containing HTML, CSS, and image files used by
133 .Nm .
134 .It Pa /tmp/
135 Directory for temporary files created by
136 .Nm .
137 .El
138 .Sh EXAMPLES
139 Example configuration for
140 .Xr httpd.conf 5 :
141 .Bd -literal -offset indent
142   types { include "/usr/share/misc/mime.types" }
143 
144   # one gotwebd reachable at http://gotweb1.example.com/
145   server "gotweb1.example.com" {
146         listen on * port 80
147         root "/htdocs/gotwebd"
148         location "/" {
149               fastcgi socket "/run/gotweb.sock"
150         }
151   }
152 
153   # hosting multiple gotwebd instances on the same HTTP server:
154   # http://gotweb2.example.com/gotwebd-unix/
155   # http://gotweb2.example.com/gotwebd-tcp/
156   server "gotweb2.example.com" {
157         listen on * port 80
158         location "/gotwebd-unix/" {
159               fastcgi socket "/run/gotweb.sock"
160         }
161         location "/gotwebd-unix/*" {
162                root "/htdocs/gotwebd"
163                request strip 1
164         }
165         location "/gotwebd-tcp/" {
166               fastcgi socket tcp 127.0.0.1 9000
167         }
168         location "/gotwebd-tcp/*" {
169                root "/htdocs/gotwebd"
170                request strip 1
171         }
172   }
173 .Ed
174 .Sh SEE ALSO
175 .Xr got 1 ,
176 .Xr git-repository 5 ,
177 .Xr gotwebd.conf 5 ,
178 .Xr httpd.conf 5 ,
179 .Xr httpd 8
180 .Sh AUTHORS
181 .An Omar Polo Aq Mt op@openbsd.org
182 .An Stefan Sperling Aq Mt stsp@openbsd.org
183 .An Tracey Emery Aq Mt tracey@traceyemery.net