aboutsummaryrefslogtreecommitdiffstats
path: root/skein.7
diff options
context:
space:
mode:
authorWynn Wolf Arbor2020-05-28 18:49:11 +0200
committerWynn Wolf Arbor2020-05-28 18:49:11 +0200
commit31b95084abb39fbb0814ba86aec442782aef112f (patch)
tree32da3f22c9403242ce42b984dfab6448fb6a11d5 /skein.7
parenta8207a5d773c514b07b555e256394b100c3df169 (diff)
downloadskein-31b95084abb39fbb0814ba86aec442782aef112f.tar.gz
Add documentation for skein(7) and skein-infra(8)0.1.0
Diffstat (limited to '')
-rw-r--r--skein.7132
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