| SKEIN(7) | Miscellaneous Information Manual | SKEIN(7) |
NAME
skein —
DESCRIPTION
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).
REPOSITORY INFRASTRUCTURE
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).
CGIT INFRASTRUCTURE
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:
/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/
A single cgit instance is comprised of the following files and directories:
- config
- The runtime configuration for cgit, as per cgitrc(5).
- repos/
- A directory holding a list of repositories available to that cgit instance, in the form of symbolic links pointing to repositories in repos.avail/.
- site/
- 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:
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
WEB SERVER CONFIGURATION
Web servers connect to slowcgi(8) via its unix socket. For simple setups it is sufficient for the web server to setSCRIPT_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
}
SEE ALSO
cgitrc(5), mount(8), skein-infra(8), slowcgi(8)| May 28, 2020 |