.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