Rewrite the README for the fork as README.txt

1 file changed, 144 insertions, 0 deletions

diff --git a/README.txt b/README.txtnew file mode 100644index 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`.
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`.