add README.mdconfig-file

1 files changed, 57 insertions, 0 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..498cfbc
--- /dev/null
+++ b/README.md
@@ -0,0 +1,57 @@
+phlox
+=====
+
+a simple, authenticated reverse-proxy server.
+
+this is intended for simple use cases, like if you have a weird little web app that may have some
+security concerns that you'd still like to be able to access on the public internet.
+
+
+configuration
+-------------
+
+phlox uses a json file for configuration. a config file should contain an object with the following keys:
+
+  * `ListenAddress`: a string containing the address to bind the server on
+  * `AssetDirectory`: a path to a directory containing various assets, described in more detail below
+  * `LoginTimeout`: the time in seconds that a user can be idle before being logged out
+  * `Users`: an array of objects, which should be generated by calling phlox with the `--passwd` flag
+  * `Endpoints`: an array of objects defining a reverse-proxy endpoint. they should contain:
+    * `Path`: the path to access the proxied resource
+    * `Address`: the remote address of the proxied resource
+
+### assets
+
+files under the `AssetDirectory` will be accessible at `/phlox/asset/`. you should be careful: if 
+`AssetDirectory` is an empty string, then phlox's current working directory will be served! if you want
+*nothing* to be accessible, set it to `/dev/null` or similar.
+
+some files in this directory are treated specially, if they exist:
+
+  * `login.html` will replace the default `/phlox/login` page. it should contain a form that POSTs
+    a username and password field to `/phlox/login` or you will probably break things.
+  * `logged_in.html` will replace the default `/phlox/login` page for users who are logged in.
+  * `404.html` will replace the default 404 error page
+  * `500.html` will replace the default 500 error page
+
+if you load any assets on these pages, they should be loaded from `/phlox/asset/` and NOT via relative
+paths, because they won't work otherwise (and indeed that's the whole point of `/phlox/asset/`).
+
+
+organization
+------------
+
+```
+  |-- README.md        this file
+  |-- main.go          the program entry point
+  |-- login.go         login & logout http handler logic
+  |-- proxy.go         proxy http handler code
+  |-- auth/
+  |   |-- auth.go      password handling & hashing
+  |   |-- session.go   session creation & management (inc. a fake in-memory session db)
+  |-- config/
+  |   |-- config.go    config structures & loading
+  |-- page/
+      |-- page.go      page loading from AssetDirectory and container structure
+      |-- default.go   definitions for the default pages when AssetDirectory ones are unavailable
+```