Blame


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 722e143e 2023-12-30 op types { include "/usr/share/misc/mime.types" }
143 dbcc187b 2022-08-30 stsp
144 722e143e 2023-12-30 op server "example.com" {
145 722e143e 2023-12-30 op listen on * port 80
146 722e143e 2023-12-30 op root "/htdocs/gotwebd"
147 722e143e 2023-12-30 op location "/" {
148 722e143e 2023-12-30 op fastcgi socket "/run/gotweb.sock"
149 722e143e 2023-12-30 op }
150 722e143e 2023-12-30 op }
151 722e143e 2023-12-30 op .Ed
152 722e143e 2023-12-30 op .Pp
153 722e143e 2023-12-30 op Hosting multiple
154 722e143e 2023-12-30 op .Nm gotwebd
155 722e143e 2023-12-30 op instances on the same HTTP server under different path prefixes, with
156 722e143e 2023-12-30 op the first reached via the default
157 722e143e 2023-12-30 op .Ux Ns -domain socket, the second configured to listen on localhost
158 722e143e 2023-12-30 op port 9000:
159 722e143e 2023-12-30 op .Bd -literal -offset indent
160 722e143e 2023-12-30 op server "example.com" {
161 722e143e 2023-12-30 op listen on * port 80
162 dbcc187b 2022-08-30 stsp
163 722e143e 2023-12-30 op location "/gotwebd-unix/" {
164 722e143e 2023-12-30 op fastcgi socket "/run/gotweb.sock"
165 722e143e 2023-12-30 op }
166 722e143e 2023-12-30 op location "/gotwebd-unix/*" {
167 722e143e 2023-12-30 op root "/htdocs/gotwebd"
168 722e143e 2023-12-30 op request strip 1
169 722e143e 2023-12-30 op }
170 722e143e 2023-12-30 op
171 722e143e 2023-12-30 op location "/gotwebd-tcp/" {
172 722e143e 2023-12-30 op fastcgi socket tcp localhost 9000
173 722e143e 2023-12-30 op }
174 722e143e 2023-12-30 op location "/gotwebd-tcp/*" {
175 722e143e 2023-12-30 op root "/htdocs/gotwebd"
176 722e143e 2023-12-30 op request strip 1
177 722e143e 2023-12-30 op }
178 722e143e 2023-12-30 op }
179 a596b957 2022-07-14 tracey .Ed
180 a596b957 2022-07-14 tracey .Sh SEE ALSO
181 a596b957 2022-07-14 tracey .Xr got 1 ,
182 a596b957 2022-07-14 tracey .Xr git-repository 5 ,
183 59975c69 2022-08-29 stsp .Xr gotwebd.conf 5 ,
184 87332a0e 2023-01-23 op .Xr httpd.conf 5 ,
185 59975c69 2022-08-29 stsp .Xr httpd 8
186 a596b957 2022-07-14 tracey .Sh AUTHORS
187 59975c69 2022-08-29 stsp .An Omar Polo Aq Mt op@openbsd.org
188 a596b957 2022-07-14 tracey .An Stefan Sperling Aq Mt stsp@openbsd.org
189 59975c69 2022-08-29 stsp .An Tracey Emery Aq Mt tracey@traceyemery.net