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

2 files changed, 144 insertions, 99 deletions

diff --git a/README b/README
deleted file mode 100644
index 7a6b4a4..0000000
--- a/README
+++ /dev/null
@@ -1,99 +0,0 @@
-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.
-
-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).
-
-If you'd like to compile without Lua support, you may use:
-
-    $ make NO_LUA=1
-
-And if you'd like to specify a Lua implementation, you may use:
-
-    $ make LUA_PKGCONFIG=lua5.1
-
-If this is not specified, the Lua implementation will be auto-detected,
-preferring LuaJIT if many are present. Acceptable values are generally "lua",
-"luajit", "lua5.1", and "lua5.2".
-
-
-Dependencies
-------------
-
-* libzip
-* libcrypto (OpenSSL)
-* libssl (OpenSSL)
-* optional: luajit or lua, most reliably used when pkg-config is available
-
-Apache configuration
---------------------
-
-A new `Directory` section must probably be added for cgit, possibly something
-like this:
-
-    <Directory "/var/www/htdocs/cgit/">
-        AllowOverride None
-        Options +ExecCGI
-        Order allow,deny
-        Allow from all
-    </Directory>
-
-
-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).
-
-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`.
-
-Online presence
----------------
-
-* The cgit homepage is hosted by cgit at <https://git.zx2c4.com/cgit/about/>
-
-* Patches, bug reports, discussions and support should go to the cgit
-  mailing list: <cgit@lists.zx2c4.com>. To sign up, visit
-  <https://lists.zx2c4.com/mailman/listinfo/cgit>
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`.