doc: installation and configuration in README

README.md

@@ -1,4 +1,52 @@
 cf-fastpush-controller
 ==
 
-Please refer to the documentation at [cf-fastpush-plugin](https://github.com/xiwenc/cf-fastpush-plugin).
+`cf-fastpush-controller` is a tiny HTTP service that works as a smart reverse proxy and supports a minimal set of remote control commands.
+
+Usage
+===
+
+`cf-fastpush-controller` on its own is not very useful. A fastpush client or specific tool plugin like [cf-fastpush-plugin](https://github.com/xiwenc/cf-fastpush-plugin) is needed to interact with the controller. For usage and general documentation on `fastpush` please refer to the documentation at [fastpush](https://github.com/xiwenc/fastpush).
+
+Installation
+===
+
+```bash
+git clone https://github.com/xiwenc/cf-fastpush-controller.git
+cd cf-fastpush-controller
+go build
+# optionally optimize the binary size
+strip -s cf-fastpush-controller
+```
+
+Configuration
+===
+
+The controller uses [viper](https://github.com/spf13/viper) Go library as configuration system. Currently `cf-fastpush-controller.yml` and `environment variables` are supported as means of configuration.
+
+| Yaml Name | Env var Name | Default value | Description |
+| --- | --- | --- | --- |
+| bind_address | BIND_ADDRESS | 0.0.0.0 | Controller binds to this address. |
+| port | PORT | 9000 | Port on which the controller listens on. |
+| backend_command | BACKEND_COMMAND | _nil_ | The command to run the backend service. |
+| backend_dirs | BACKEND_DIRS | ./ | Space separated list of directories that contain application files. |
+| backend_port | BACKEND_PORT | 8080 | Port on which the backend service listens on. For compatibility with CF/Heroku the `PORT` environment variable is set to `BACKEND_PORT` value before calling the `BACKEND_COMMAND`. |
+| restart_regex | RESTART_REGEX | `^*.py$` | The backend service is restarted if a changed file's name matches this regex. |
+| ignore_regex | IGNORE_REGEX | _nil_ | If a changed file's name matches this regex a restart will not be executed. |
+| base_path | BASE_PATH | `/_fastpush` | This is the URL path on which the controller accepts control commands. Only change this if you know what you are doing because this value must match with the client configuration that sends control messages. |
+
+REST API
+===
+
+| Path | Method | Description |
+| --- | --- | --- |
+| /files | GET | Get current list of files with their hashes |
+| /files | PUT | Upload new or update existing files |
+| /restart | POST | Restart the backend service |
+| /status | GET | Get the current status of the backend service |
+
+
+Authentication
+===
+
+Currently the controller is protected using a `x-auth-token` HTTP Header and is only enabled when deploying to Cloud Foundry or Heroku (not yet tested).  We are considering to make the token value configurable for more flexibility and security.