update documentation

2 files changed, 34 insertions, 1 deletions

diff --git a/README b/README
index 6ba0fbd..09b1bbf 100644
--- a/README
+++ b/README
@@ -1,3 +1,33 @@
 Dedicated syntax highlighting server for cgit.
 
-Mitigates the issue of python import time for cgit source-filters.
+Use a simple HTTP server to highlight source for cgit. Improves performance
+compared to invoking python on every request.
+
+Usage:
+
+1. Run `make install`.
+2. Configure your system to run /usr/lib/cgit/syntax-highlighting-server.py at
+   boot. This can be done by `systemctl enable syntax-highlighting` on systemd
+   machines. Note that syntax-highlighting-server is very insecure. Therefore,
+   do not configure it to listen on a public network.
+3. Set your cgit source filter to syntax-highlighting-client.sh.
+
+Tuning:
+
+By default, syntax-highlighting-server does all work in a single thread. If you
+have a high query load and multiple CPUs, consider setting --listen-mode to
+forking or reuseport.
+
+reuseport mode uses one worker per CPU and is the highest performance mode, but
+requires Linux and additional idle memory (roughly 1-3 MB per worker).
+
+forking mode uses less idle memory and is compatible with non-Linux systems,
+but is significantly less efficient, since it forks for every request.
+
+Security:
+
+syntax-highlighting-server is not hardened against malicious clients which send
+malformed data or are simply excessively slow. Once again, do not configure
+syntax-highlighting-server to listen on a public network. It is also
+recommended to set max-blob-size in cgitrc, as the entire file must be buffered
+in memory during syntax highlighting.
diff --git a/syntax-highlighting-server.py b/syntax-highlighting-server.py
index dabd631..05140a7 100755
--- a/syntax-highlighting-server.py
+++ b/syntax-highlighting-server.py
@@ -117,6 +117,9 @@ def main():
             .format(args.host, args.port))
 
     try:
+        # preload stuff to avoid first-request latency (every request for
+        # forking) and post-fork memory usage
+
         # preload lexers
         guess_lexer('')
         # preload formatter