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