Rewrite the README for the fork as `README.txt`

1 file changed, 144 insertions, 0 deletions

diff --git a/README.txt b/README.txt
new file mode 100644
index 0000000..b1ab036
--- /dev/null
+++ b/README.txt
@@ -0,0 +1,144 @@
+cgit - CGI for Git
+==================
+
+This is an attempt to create a fast web interface for the Git SCM, using a
+built-in cache to decrease server I/O pressure.
+
+
+Repository layout
+-----------------
+
+    source/      the C sources, the build fragment and the version script
+    libraries/   the bundled Git tree, tracked as a submodule
+    assets/      cgit.css, cgit.js and the images cgit serves
+    extensions/  optional runtime filter scripts
+    examples/    a commented cgitrc, git hooks and web server configs
+    tools/       developer tooling (preview server and release build)
+    tests/       the test suite
+    build/       everything the build generates, and not tracked in git
+
+
+Installation
+------------
+
+Building cgit involves building a proper version of Git. How to do this depends
+on how you obtained the cgit sources:
+
+a) If you're working in a cloned cgit repository, you first need to initialize
+and update the Git submodule:
+
+    $ git submodule init     # register the Git submodule in .git/config
+    $ $EDITOR .git/config    # if you want to specify a different url for git
+    $ git submodule update   # clone/fetch and checkout correct git version
+
+b) If you're building from a cgit tarball, you can download a proper git version
+like this:
+
+    $ make get-git
+
+When either a) or b) has been performed, you can build and install cgit like
+this:
+
+    $ make
+    $ sudo make install
+
+This will install `cgit.cgi` and `cgit.css` into `/var/www/htdocs/cgit`. You can
+configure this location (and a few other things) by providing a `cgit.conf` file
+(see the Makefile for details).
+
+Lua is optional and only powers the lua: filter extensions (authentication,
+email and commit-message filters in extensions/). A plain build auto-detects a
+Lua through pkg-config, preferring LuaJIT, and falls back to a Lua-less binary
+when none is found. Acceptable values are generally "luajit", "lua", "lua5.4",
+"lua5.3", "lua5.2" and "lua5.1".
+
+To pin an implementation:
+
+    $ make LUA_PKGCONFIG=lua5.4
+
+To build without Lua, so the binary needs no Lua at runtime:
+
+    $ make NO_LUA=1
+
+
+Previewing locally
+------------------
+
+cgit is a CGI program, so trying it out normally means configuring a web server.
+For development there is a small dependency-free preview server at
+`tools/serve.py` that runs the built binary and serves the static assets. It
+needs only Python 3.
+
+    $ python3 tools/serve.py --config /path/to/cgitrc --port 8080
+
+It is a development aid and is not meant to face the internet.
+
+
+Dependencies
+------------
+
+* zlib
+* optional: luajit or lua, most reliably used when pkg-config is available
+
+cgit builds without OpenSSL or libcurl, so no development packages for those are
+needed.
+
+
+Web server configuration
+------------------------
+
+cgit is a CGI program. Complete, commented configurations for nginx, Apache and
+lighttpd live in `examples/servers/`, each explaining how that server routes
+requests to the binary and serves the static assets off disk.
+
+
+Runtime configuration
+---------------------
+
+The file `/etc/cgitrc` is read by cgit before handling a request. In addition to
+runtime parameters, this file may also contain a list of repositories displayed
+by cgit (see `cgitrc.5.txt` for further details). A fully commented starting
+point with every option at its default is in `examples/cgitrc`.
+
+
+Securing an instance
+--------------------
+
+A public instance needs a few deliberate choices, all set in cgitrc and
+documented in `cgitrc.5.txt`.
+
+* Keep private repositories out of `scan-path`, or set `strict-export` to a
+  marker filename so only repositories that contain it are published.
+
+* Gate the whole instance behind a login with `auth-filter`. Two example filters
+  ship in `extensions/`, `auth-inline.lua` and `auth-file.lua`.
+
+* Terminate TLS at the web server in front of cgit.
+
+* The example configs in `examples/servers/` set a Content-Security-Policy and
+  related headers at the web server, where they also cover the static assets.
+
+* `max-blob-size` bounds how much a single request reads into memory, and
+  defaults to 10 MB.
+
+* Leave `enable-cache-list` off, since it exposes the cache path and the URLs
+  other visitors requested.
+
+* Build the deployed binary with the hardening flags via
+  `tools/release-build.sh`.
+
+
+The cache
+---------
+
+When cgit is invoked it looks for a cache file matching the request and returns
+it to the client. If no such cache file exists (or if it has expired), the
+content for the request is written into the proper cache file before the file is
+returned.
+
+If the cache file has expired but cgit is unable to obtain a lock for it, the
+stale cache file is returned to the client. This is done to favour page
+throughput over page freshness.
+
+The generated content contains the complete response to the client, including
+the HTTP headers `Modified` and `Expires`.