diff options
| -rw-r--r-- | README.md | 57 |
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 +``` |