gotwebd/gotwebd.8

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