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