diff options
Diffstat (limited to 'skein.7')
| -rw-r--r-- | skein.7 | 132 |
1 files changed, 132 insertions, 0 deletions
@@ -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 |