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 55331ef5 2022-08-30 thomas .Nd Game of Trees Git Fast-CGI repository server for web browsers
 22 8a35f56c 2022-07-16 thomas .Sh SYNOPSIS
 23 8a35f56c 2022-07-16 thomas .Nm
 24 8a35f56c 2022-07-16 thomas .Sh DESCRIPTION
 25 8a35f56c 2022-07-16 thomas .Nm
 26 55331ef5 2022-08-30 thomas is a Fast-CGI server program which can display the contents of Git
 27 55331ef5 2022-08-30 thomas repositories via a web browser.
 28 8a35f56c 2022-07-16 thomas The program has been designed to work out of the box with
 29 8a35f56c 2022-07-16 thomas the
 30 8a35f56c 2022-07-16 thomas .Xr httpd 8
 31 55331ef5 2022-08-30 thomas web server.
 32 8a35f56c 2022-07-16 thomas .Pp
 33 8a35f56c 2022-07-16 thomas Enabling
 34 8a35f56c 2022-07-16 thomas .Nm
 35 8a35f56c 2022-07-16 thomas requires the following steps:
 36 8a35f56c 2022-07-16 thomas .Bl -enum
 37 8a35f56c 2022-07-16 thomas .It
 38 8a35f56c 2022-07-16 thomas The
 39 8a35f56c 2022-07-16 thomas .Xr httpd.conf 5
 40 8a35f56c 2022-07-16 thomas configuration file must be adjusted to run
 41 8a35f56c 2022-07-16 thomas .Nm
 42 55331ef5 2022-08-30 thomas as a Fast-CGI helper program.
 43 8a35f56c 2022-07-16 thomas The
 44 8a35f56c 2022-07-16 thomas .Sx EXAMPLES
 45 8a35f56c 2022-07-16 thomas section below contains an appropriate configuration file sample.
 46 8a35f56c 2022-07-16 thomas .It
 47 55331ef5 2022-08-30 thomas httpd(8) must be enabled and started:
 48 8a35f56c 2022-07-16 thomas .Bd -literal -offset indent
 49 55331ef5 2022-08-30 thomas   # rcctl enable httpd
 50 55331ef5 2022-08-30 thomas   # rcctl start httpd
 51 8a35f56c 2022-07-16 thomas .Ed
 52 8a35f56c 2022-07-16 thomas .It
 53 8a35f56c 2022-07-16 thomas Optionally, the run-time behaviour of
 54 8a35f56c 2022-07-16 thomas .Nm
 55 8a35f56c 2022-07-16 thomas can be configured via the
 56 55331ef5 2022-08-30 thomas .Xr gotwebd.conf 5
 57 8a35f56c 2022-07-16 thomas configuration file.
 58 8a35f56c 2022-07-16 thomas .It
 59 8a35f56c 2022-07-16 thomas Git repositories must be created at a suitable location inside the
 60 8a35f56c 2022-07-16 thomas web server's
 61 8a35f56c 2022-07-16 thomas .Xr chroot 2
 62 8a35f56c 2022-07-16 thomas environment.
 63 8a35f56c 2022-07-16 thomas These repositories should
 64 8a35f56c 2022-07-16 thomas .Em not
 65 116aeeba 2022-08-30 thomas be writable by the user ID shared between
 66 116aeeba 2022-08-30 thomas .Nm
 67 116aeeba 2022-08-30 thomas and
 68 116aeeba 2022-08-30 thomas .Xr httpd 8 .
 69 8a35f56c 2022-07-16 thomas The default location for repositories published by
 70 8a35f56c 2022-07-16 thomas .Nm
 71 8a35f56c 2022-07-16 thomas is
 72 8a35f56c 2022-07-16 thomas .Pa /var/www/got/public .
 73 8a35f56c 2022-07-16 thomas .It
 74 8a35f56c 2022-07-16 thomas Git repositories served by
 75 8a35f56c 2022-07-16 thomas .Nm
 76 8a35f56c 2022-07-16 thomas should be kept up-to-date with a mechanism such as
 77 8a35f56c 2022-07-16 thomas .Cm got fetch ,
 78 8a35f56c 2022-07-16 thomas .Xr git-fetch 1 ,
 79 8a35f56c 2022-07-16 thomas or
 80 8a35f56c 2022-07-16 thomas .Xr rsync 1 ,
 81 8a35f56c 2022-07-16 thomas scheduled by
 82 8a35f56c 2022-07-16 thomas .Xr cron 8 .
 83 8a35f56c 2022-07-16 thomas .El
 84 8a35f56c 2022-07-16 thomas .Sh FILES
 85 8a35f56c 2022-07-16 thomas .Bl -tag -width /var/www/got/public/ -compact
 86 8a35f56c 2022-07-16 thomas .It Pa /var/www/got/public/
 87 8a35f56c 2022-07-16 thomas Default location for Git repositories served by
 88 8a35f56c 2022-07-16 thomas .Nm .
 89 8a35f56c 2022-07-16 thomas This location can be adjusted in the
 90 55331ef5 2022-08-30 thomas .Xr gotwebd.conf 5
 91 8a35f56c 2022-07-16 thomas configuration file.
 92 55331ef5 2022-08-30 thomas .It Pa /var/www/bin/gotwebd/
 93 8a35f56c 2022-07-16 thomas Directory containing statically linked
 94 8a35f56c 2022-07-16 thomas .Xr got 1
 95 8a35f56c 2022-07-16 thomas helper programs which are run by
 96 8a35f56c 2022-07-16 thomas .Nm
 97 8a35f56c 2022-07-16 thomas to read Git repositories.
 98 55331ef5 2022-08-30 thomas .It Pa /var/www/htdocs/gotwebd/
 99 8a35f56c 2022-07-16 thomas Directory containing HTML, CSS, and image files used by
100 8a35f56c 2022-07-16 thomas .Nm .
101 55331ef5 2022-08-30 thomas .It Pa /tmp/
102 8a35f56c 2022-07-16 thomas Directory for temporary files created by
103 8a35f56c 2022-07-16 thomas .Nm .
104 8a35f56c 2022-07-16 thomas .El
105 8a35f56c 2022-07-16 thomas .Sh EXAMPLES
106 8a35f56c 2022-07-16 thomas Example configuration for httpd.conf:
107 8a35f56c 2022-07-16 thomas .Bd -literal -offset indent
108 8a35f56c 2022-07-16 thomas   types { include "/usr/share/misc/mime.types" }
109 ab451195 2022-08-30 thomas 
110 ab451195 2022-08-30 thomas   # one gotwebd reachable at http://gotweb1.example.com/
111 ab451195 2022-08-30 thomas   server "gotweb1.example.com" {
112 ab451195 2022-08-30 thomas         listen on * port 80
113 ab451195 2022-08-30 thomas         root "/htdocs/gotwebd"
114 ab451195 2022-08-30 thomas         location "/" {
115 ab451195 2022-08-30 thomas               fastcgi socket tcp localhost 9000
116 ab451195 2022-08-30 thomas         }
117 ab451195 2022-08-30 thomas   }
118 ab451195 2022-08-30 thomas 
119 ab451195 2022-08-30 thomas   # hosting multiple gotwebd instances on the same HTTP server:
120 ab451195 2022-08-30 thomas   # http://gotweb2.example.com/gotwebd-unix/
121 ab451195 2022-08-30 thomas   # http://gotweb2.example.com/gotwebd-tcp/
122 ab451195 2022-08-30 thomas   server "gotweb2.example.com" {
123 ab451195 2022-08-30 thomas         listen on * port 80
124 ab451195 2022-08-30 thomas         location "/gotwebd-unix/" {
125 55331ef5 2022-08-30 thomas               fastcgi socket "/run/gotweb.sock"
126 55331ef5 2022-08-30 thomas         }
127 ab451195 2022-08-30 thomas         location "/gotwebd-unix/*" {
128 ab451195 2022-08-30 thomas                root "/htdocs/gotwebd"
129 ab451195 2022-08-30 thomas                request strip 1
130 ab451195 2022-08-30 thomas         }
131 ab451195 2022-08-30 thomas         location "/gotwebd-tcp/" {
132 55331ef5 2022-08-30 thomas               fastcgi socket tcp 127.0.0.1 9000
133 55331ef5 2022-08-30 thomas         }
134 ab451195 2022-08-30 thomas         location "/gotwebd-tcp/*" {
135 ab451195 2022-08-30 thomas                root "/htdocs/gotwebd"
136 ab451195 2022-08-30 thomas                request strip 1
137 55331ef5 2022-08-30 thomas         }
138 8a35f56c 2022-07-16 thomas   }
139 8a35f56c 2022-07-16 thomas .Ed
140 8a35f56c 2022-07-16 thomas .Sh SEE ALSO
141 8a35f56c 2022-07-16 thomas .Xr got 1 ,
142 8a35f56c 2022-07-16 thomas .Xr git-repository 5 ,
143 55331ef5 2022-08-30 thomas .Xr gotwebd.conf 5 ,
144 55331ef5 2022-08-30 thomas .Xr httpd 8
145 8a35f56c 2022-07-16 thomas .Sh AUTHORS
146 55331ef5 2022-08-30 thomas .An Omar Polo Aq Mt op@openbsd.org
147 8a35f56c 2022-07-16 thomas .An Stefan Sperling Aq Mt stsp@openbsd.org
148 55331ef5 2022-08-30 thomas .An Tracey Emery Aq Mt tracey@traceyemery.net