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

1 files changed, 132 insertions, 0 deletions

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