Add documentation for skein(7) and skein-infra(8)0.1.0

3 files changed, 192 insertions, 1 deletions

diff --git a/Makefile b/Makefile
index cf54451..3202fb7 100644
--- a/Makefile
+++ b/Makefile
@@ -1,6 +1,7 @@
 PREFIX ?= /usr/local
 LIBEXECDIR ?= ${PREFIX}/libexec
 SBINDIR ?= ${PREFIX}/sbin
+MANDIR ?= ${PREFIX}/share/man
 
 CFLAGS ?= -O2 -pipe -s
 CFLAGS += -Wall -Wextra -Wpedantic -Werror
@@ -10,9 +11,11 @@ LDFLAGS ?= -static
 cgit-about-filter: cgit-about-filter.c
 	${CC} -o $@ ${CFLAGS} ${LDFLAGS} $<
 
-install: cgit-about-filter skein-infra
+install: cgit-about-filter skein-infra skein.7 skein-infra.8
 	install -D -m 755 -t '${DESTDIR}${LIBEXECDIR}/skein' cgit-about-filter
 	install -D -m 755 -t '${DESTDIR}${SBINDIR}' skein-infra
+	install -D -m 644 -t '${DESTDIR}${MANDIR}/man7' skein.7
+	install -D -m 644 -t '${DESTDIR}${MANDIR}/man8' skein-infra.8
 
 clean:
 	rm cgit-about-filter
diff --git a/skein-infra.8 b/skein-infra.8
new file mode 100644
index 0000000..5c7c400
--- /dev/null
+++ b/skein-infra.8
@@ -0,0 +1,56 @@
+.Dd May 28, 2020
+.Dt SKEIN-INFRA 8
+.Os
+.Sh NAME
+.Nm skein-infra
+.Nd set up devices and bind mounts for
+.Xr skein 7
+.Sh SYNOPSIS
+.Nm
+.Ar setup
+.Nm
+.Ar teardown
+.Sh DESCRIPTION
+.Nm
+is a utility which sets up all necessary devices and bind mounts for the
+.Xr skein 7
+cgit infrastructure.
+.Pp
+The commands are as follows:
+.Bl -tag -width Ds
+.It Sy setup
+Creates
+.Pa /dev/null
+under
+.Ev SKEIN_CGIT_ROOT
+and sets up all necessary bind mounts.
+.Pp
+Each user's git directory under
+.Ev SKEIN_GIT_ROOT
+is mounted on the corresponding
+.Pa repos.avail/
+mount point in their cgit home directory.
+.It Sy teardown
+Deletes
+.Pa /dev/null
+and all existing bind mounts under
+.Ev SKEIN_CGIT_ROOT .
+.El
+.Sh ENVIRONMENT
+.Bl -tag -width Ds
+.It Ev SKEIN_CGIT_ROOT
+The
+.Xr skein 7
+cgit infrastructure.
+Defaults to
+.Pa /srv/cgit .
+.It Ev SKEIN_GIT_ROOT
+The
+.Xr skein 7
+repository infrastructure.
+Defaults to
+.Pa /srv/git .
+.El
+.Sh SEE ALSO
+.Xr skein 7 ,
+.Xr mount 8
diff --git a/skein.7 b/skein.7
new file mode 100644
index 0000000..5f85711
--- /dev/null
+++ b/skein.7
@@ -0,0 +1,132 @@
+.Dd May 28, 2020
+.Dt SKEIN 7
+.Os
+.Sh NAME
+.Nm skein
+.Nd secure cgit hosting with
+.Xr slowcgi 8
+.Sh DESCRIPTION
+.Nm
+is a framework for building a secure cgit hosting platform.
+It uses
+.Xr slowcgi 8
+to provide cgit to modern web servers that only support FastCGI and
+keeps the entire cgit platform jailed in a chroot.
+Users may host multiple cgit instances, each with their own repositories
+and cgit configuration.
+.Pp
+The framework is comprised of two main parts, the cgit infrastructure
+and the repository infrastructure.
+These two parts exist independent of each other, allowing other
+applications access to repositories without having to be integrated into
+the framework.
+.Pp
+.Nm
+utilizes bind mounts to allow access to the repositories from within the
+chroot.
+Each user will have their available repositories accessible through a
+mount point in their cgit home directory.
+Bind mounts and other necessary devices may be set up using
+.Xr skein-infra 8 .
+.Sh REPOSITORY INFRASTRUCTURE
+Bare Git repositories are stored in per-user folders under
+.Pa /srv/git .
+.Pp
+Repositories that are meant to be accessed by cgit should be readable by
+the user running
+.Xr slowcgi 8 .
+.Sh CGIT INFRASTRUCTURE
+The cgit infrastructure exists in
+.Pa /srv/cgit .
+This directory also acts as the chroot directory for
+.Xr slowcgi 8 ,
+containing the cgit CGI executable itself, along with other programs
+relevant to cgit instances, such as formatters and filters like
+.Xr mandoc 1
+or
+.Xr lowdown 1 ,
+and archivers or compression programs like
+.Xr tar 1
+or
+.Xr gzip 1 .
+.Pp
+Each user owns a home directory which contains a mount point
+.Pa repos.avail/
+for the user's available repositories and
+a folder
+.Pa instances/
+that contains every instance managed by that user.
+.Pp
+For example, a setup with two users may look like this:
+.Bd -literal -offset indent
+/srv/cgit
+├── bin
+│   ├── cgit
+│   └── mandoc
+└── home
+    ├── ada
+    │   ├── instances
+    │   │   └── cgit.ada.example.org/
+    │   └── repos.avail/
+    └── joe
+        ├── instances
+        │   ├── cgit.joe.example.org/
+        │   └── private-cgit.joe.example.org/
+        └── repos.avail/
+.Ed
+.Pp
+A single cgit instance is comprised of the following files and
+directories:
+.Bl -tag -width Ds
+.It Sy config
+The runtime configuration for cgit, as per
+.Xr cgitrc 5 .
+.It Sy repos/
+A directory holding a list of repositories available to that cgit
+instance, in the form of symbolic links pointing to repositories in
+.Pa repos.avail/ .
+.It Sy site/
+A directory containing static resources needed for cgit.
+This is also the website's root directory.
+.El
+.Pp
+For example, a single instance may look like this:
+.Bd -literal -offset indent
+cgit.joe.example.org
+├── config
+├── repos
+│   ├── dotfiles.git@ -> ../../../repos.avail/dotfiles.git
+│   └── project.git@  -> ../../../repos.avail/project.git
+└── site
+    ├── cgit.css
+    ├── favicon.ico
+    └── logo.png
+.Ed
+.Sh WEB SERVER CONFIGURATION
+Web servers connect to
+.Xr slowcgi 8
+via its unix socket.
+For simple setups it is sufficient for the web server to set
+.Ev SCRIPT_FILENAME
+and
+.Ev CGIT_CONFIG .
+Note that static files such as
+.Pa cgit.css
+or
+.Pa cgit.png
+need to be excluded from FastCGI processing.
+.Pp
+For example, a FastCGI directive may look like this:
+.Bd -literal -offset indent
+fastcgi / /run/slowcgi.cgit.sock {
+	env SCRIPT_FILENAME /bin/cgit.cgi
+	env CGIT_CONFIG /home/joe/instances/cgit.joe.example.org/config
+
+	except /cgit.css /cgit.png /favicon.ico /robots.txt
+}
+.Ed
+.Sh SEE ALSO
+.Xr cgitrc 5 ,
+.Xr mount 8 ,
+.Xr skein-infra 8 ,
+.Xr slowcgi 8