Written in 2019 by Eliah Kagan <[email protected]>.
To the extent possible under law, the author(s) have dedicated all copyright and related and neighboring rights to this software to the public domain worldwide. This software is distributed without any warranty.
You should have received a copy of the CC0 Public Domain Dedication along with this software. If not, see http://creativecommons.org/publicdomain/zero/1.0/.
The scripts and associated files in this repository automate and document the installation and configuration of cgit that works well for me in the undemanding environment of a web server that is not directly accessible on the public internet and that has only a handful of users.
The scripts can be run individually, or all together by just running
./setup-all. They should all be run from the directory in which they
reside unless you really know what you are doing. They look in the current
directory to find the files they use, so unless you're deliberately making them
use different files instead, you should make sure to cd to the directory
they're in. For example, cd /path/to/this/repo followed by ./setup-all
would do the right thing (but /path/to/this/repo/setup-all would do the wrong
thing).
I learned some of the techniques used and described here from Floating Octothorpe, especially:
The remainder of this document describes the individual steps that should be taken to set up cgit. It is organized by the files in this repository that relate to each step.
cgit needs git and a web server. Other software comes in handy to provide
syntax highlighting. Running ./install-services installs packages for all
this and performs site-nonspecific configuration. cgid is enabled for
performance. Debian or a derivative (such as Ubuntu) is assumed.
Copy cgitrc to /etc as root to replace the existing cgit configuration with
an arrangement where repositories in /repos are automatically browseable via
the cgit web interface, accessible at http://HOST/cgit where HOST is replaced
by a domain name, hostname, or IP address through which the HTTP server on this
system may be accessed.
Backing up the existing /etc/cgitrc first would be a good idea. One way to
achieve this is to run ./deploy-cgitrc to perform the copying, as it backs up
the old file unless the files are the same (in which case no backup is made, to
avoid overwriting an existing backup with a copy of the current file).
Syntax highlighting is provided by pygments. The python3-pygments package
should be installed. I've used pygments instead of highlight because pygments
works out of the box with files that have no suffix and whose language must
therefore be inferred from their hashbangs.
A README.md at the root of a repository is used as documentation. This isn't
really robust enough; ideally, a variety of files could serve the purpose, and
tie-breaking would distinguish which were best. (This can be done but I haven't
written the configuration for it.)
All repositories are listed on one page, unless there's a huge lot of them.
Place this in /var/www/html (or wherever its location is specified in
cgitrc) to create an about tab on the main page with the contents of the
file rendered in it. Running ./deploy-about-cgit as root (or some other user
wit write access in /var/www/html) will do this.
Or remove or comment out the root-readme line in cgitrc.
Running ./deploy-acl-repos as root places acl-repos and unacl-repos
commands in /usr/local/bin.
The acl-repos command applies ACLs recursively to /repos, and sets defaults
that apply to subsequently created files, so that the www-data user can read
everything in /repos. This is potentially dangerous if sensitive data are
ever stored there!
The unacl-repos command recursively removes all ACLs from /repos. This
may include ACLs that have nothing to do with those created or changed by a
previous run of acl-repos.
Neither of these commands is expected to succeed except when run as root.
Running ./deploy-redirect as root installs redirect.conf as a configuration
file for the Apache2 web server and enables it.
This configuration file redirects traffic from the root of the web server to
the cgit directory. Note that it does not prevent files in the root or
elsewhere from being accessed by a correct URL, if they otherwise could.