Add documentation.

1 files changed, 86 insertions, 0 deletions

diff --git a/README b/README
new file mode 100644
index 0000000..f3bd5d4
--- /dev/null
+++ b/README
@@ -0,0 +1,86 @@
+* Overview
+
+This is a simple HTTP server for serving static files. It was suitable
+as a lightweight replacement for full-fledged HTTP servers on sites
+where only sporadic serving of static data is needed.
+
+One of such use cases is deployment of LetsEncrypt certificates on a
+server that runs only proxy software, such as pound[1] or haproxy[2]. In
+this case using e.g. Apache or even lighttpd just to serve
+LetsEncrypt challenge requests arriving once in 90 days is clearly an
+overkill. Instead, fileserv can be used.
+
+Start the program as
+
+ fileserv -u nobody -a 127.0.0.1 /.well-known/acme-challenge:/var/www/acme/
+ 
+It will be running in background with privileges of the user nobody,
+listening on localhost, port 8080. Requests with URL path beginning
+with /.well-known/acme-challenge will be served from directory
+/var/www/acme. Other requests will be rejected.
+
+If the proxy used is pound[1], define the following service in its
+configuration file /etc/pound.conf:
+
+ Service
+     URL "^/.well-known/acme-challenge"
+     BackEnd
+         Address 127.0.0.1
+         Port 8080
+     End
+ End
+
+This will forward LetsEncrypt challenge requests to fileserv. Make
+sure this service declaration is located before all other services, so
+that it takes precedence over them.
+
+If using haproxy[2], use the following fragment (supposing the default
+backend is called dfl) in /etc/haproxy/haproxy.cfg:
+
+ frontend http-in
+    bind *:80
+    default_backend dfl
+    acl letsencrypt path_beg /.well-known/acme-challenge
+    use_backend fileserv if letsencrypt
+
+ backend fileserv
+    server localhost 127.0.0.1:8080
+
+* Building
+
+To build fileserv you will need GNU Libmicrohttpd library[3]. It is
+available for download from http://ftp.gnu.org/gnu/libmicrohttpd.
+
+When building from source package, usual incantations apply:
+
+ ./configure
+ make
+ make install
+
+If you are building from a clone of the Git repository, you will need
+GNU autotools to bootstrap the package first. Run
+
+  autoreconf -f -i -s
+
+in the top level source directory. This will create the configure
+script and populate the directory with the missing files. Then proceed
+as described above.
+
+* Documentation
+
+Manpage fileserv.3 included. After installing the package, run
+man fileserv.
+    
+* References
+
+[1] Pound - http://www.apsis.ch/pound
+[2] Haproxy - http://www.haproxy.org
+[3] GNU Libmicrohttpd - https://www.gnu.org/software/libmicrohttpd
+
+Local Variables:
+mode: outline
+paragraph-separate: "[ 	]*$"
+version-control: never
+End:
+
+