SKEIN(7) Miscellaneous Information Manual SKEIN(7)

secure cgit hosting with slowcgi(8)

skein is a framework for building a secure cgit hosting platform. It uses 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.

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.

skein 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 skein-infra(8).

Bare Git repositories are stored in per-user folders under /srv/git.

Repositories that are meant to be accessed by cgit should be readable by the user running slowcgi(8).

The cgit infrastructure exists in /srv/cgit. This directory also acts as the chroot directory for slowcgi(8), containing the cgit CGI executable itself, along with other programs relevant to cgit instances, such as formatters and filters like mandoc(1) or lowdown(1), and archivers or compression programs like tar(1) or gzip(1).

Each user owns a home directory which contains a mount point repos.avail/ for the user's available repositories and a folder instances/ that contains every instance managed by that user.

For example, a setup with two users may look like this:

├── 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/

A single cgit instance is comprised of the following files and directories:

The runtime configuration for cgit, as per cgitrc(5).
A directory holding a list of repositories available to that cgit instance, in the form of symbolic links pointing to repositories in repos.avail/.
A directory containing static resources needed for cgit. This is also the website's root directory.

For example, a single instance may look like this:

├── config
├── repos
│   ├── dotfiles.git@ -> ../../../repos.avail/dotfiles.git
│   └── project.git@  -> ../../../repos.avail/project.git
└── site
    ├── cgit.css
    ├── favicon.ico
    └── logo.png

Web servers connect to slowcgi(8) via its unix socket. For simple setups it is sufficient for the web server to set SCRIPT_FILENAME and CGIT_CONFIG. Note that static files such as cgit.css or cgit.png need to be excluded from FastCGI processing.

For example, a FastCGI directive may look like this:

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

cgitrc(5), mount(8), skein-infra(8), slowcgi(8)
May 28, 2020