Blame


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