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