summaryrefslogtreecommitdiff
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md57
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
+```