docs: add install instructions (#143)

* add install instructions s Signed-off-by: Michael Beemer <beeme1mr@users.noreply.github.com> * Update README.md Co-authored-by: Todd Baert <toddbaert@gmail.com> Signed-off-by: Michael Beemer <beeme1mr@users.noreply.github.com> * add note about systemd Signed-off-by: Michael Beemer <beeme1mr@users.noreply.github.com> * move configuration options link Signed-off-by: Michael Beemer <beeme1mr@users.noreply.github.com> Signed-off-by: Michael Beemer <beeme1mr@users.noreply.github.com> Co-authored-by: Todd Baert <toddbaert@gmail.com>
open-feature · Aug 17, 2022 · 5cc5cfb · 5cc5cfb
1 parent da2d009
commit 5cc5cfb
Show file tree

Hide file tree

Showing 4 changed files with 91 additions and 47 deletions.
diff --git a/README.md b/README.md
@@ -5,119 +5,163 @@
 ![version](https://img.shields.io/badge/version-pre--alpha-green)
 ![status](https://img.shields.io/badge/status-not--for--production-red)
 
-Flagd is a simple command line tool for fetching and presenting feature flags to services. It is designed to conform to OpenFeature schema for flag definitions.
+Flagd is a simple command line tool for fetching and evaluating feature flags for services. It is designed to conform with the OpenFeature specification.
 
-<img src="images/of-flagd-0.png" width="560">
+## Install
+
+### Go binary
+
+1. Install Go 1.18 or above
+1. run `go install github.com/open-feature/flagd@latest`
+
+### Docker
+
+1. `docker pull ghcr.io/open-feature/flagd:latest`
+
+> NOTE: It is possible to run flagD as a systemd service. Installation instructions can be found [here](./docs/systemd-service.md).
 
 ## Example usage
 
-1. Generate the prerequisites `make generate`
-2. Build the flagd binary: `make build`
-3. Start the process: `./flagd start -f config/samples/example_flags.json --service-provider http --sync-provider filepath`
+1. Download sample flag configurations: `curl https://raw.githubusercontent.com/open-feature/flagd/main/config/samples/example_flags.json -o example_flags.json`
+1. Run one of the following commands based on how flagD was installed:
+   - Go binary: `flagd start -f example_flags.json`
+   - Docker: `docker run -p 8013:8013 -v $(pwd)/:/etc/flagd/ -it ghcr.io/open-feature/flagd:latest start --uri /etc/flagd/example_flags.json`
+1. Changes made in `example_flags.json` will immediately take affect. Go ahead, give a shot!
+
+This now provides an accessible http or [https](#https) endpoint for flag evaluation. A complete list of supported configuration options can be seen [here](./docs/configuration.md).
 
-This now provides an accessible http or [https](#https) endpoint for the flags:
 ### Resolve a boolean value
 
 Command:
+
 ```sh
 curl -X POST "localhost:8013/flags/myBoolFlag/resolve/boolean"
 ```
+
 Result:
+
 ```sh
 {"value":true,"reason":"STATIC","variant":"on"}
 ```
+
 <br />
 
 ### Resolve a string value
 
 Command:
+
 ```sh
 curl -X POST "localhost:8013/flags/myStringFlag/resolve/string"
 ```
+
 Result:
+
 ```sh
 {"value":"val1","reason":"STATIC","variant":"key1"}
 ```
+
 <br />
 
 ### Resolve a integer value
 
 Command:
+
 ```sh
 curl -X POST "localhost:8013/flags/myIntFlag/resolve/int"
 ```
+
 Result:
+
 ```sh
 {"value":"1","reason":"STATIC","variant":"one"}
 ```
+
 [Why is this `int` response a `string`?](./docs/http_int_response.md)
 <br />
 <br />
 
 ### Resolve a float value
 
 Command:
+
 ```sh
 curl -X POST "localhost:8013/flags/myFloatFlag/resolve/float"
 ```
+
 Result:
+
 ```sh
 {"value":1.23,"reason":"STATIC","variant":"one"}
 ```
+
 <br />
 
 ### Resolve an object value
 
 Command:
+
 ```sh
 curl -X POST "localhost:8013/flags/myObjectFlag/resolve/object"
 ```
+
 Result:
+
 ```sh
 {"value":{"key":"val"},"reason":"STATIC","variant":"object1"}
 ```
+
 <br />
 
 ### Resolve a boolean value with evaluation context
 
 Command:
+
 ```sh
 curl -X POST "localhost:8013/flags/isColorYellow/resolve/boolean" -d '{"color": "yellow"}'
 ```
+
 Result:
+
 ```sh
 {"value":true,"reason":"TARGETING_MATCH","variant":"on"}
 ```
+
 <br />
 
 ### Return value type mismatch error
 
 A type mismatch error is returned when the resolved value of a flag does not match the type requested. In the example below, the resolved value of `myBoolFlag` is a `boolean` but the request expects a `string` to be returned.
 
 Command:
+
 ```sh
 curl -X POST "localhost:8013/flags/myBoolFlag/resolve/string"
 ```
+
 Result:
+
 ```sh
 {"error_code":"TYPE_MISMATCH","reason":"ERROR"}
 ```
+
 <br />
 
 ### Return flag not found error
 
 The flag not found error is returned when flag key in the request doesn't match any configured flags.
 
 Command:
+
 ```sh
 curl -X POST "localhost:8013/flags/aMissingFlag/resolve/string"
 ```
+
 Result:
+
 ```sh
 {"error_code":"FLAG_NOT_FOUND","reason":"ERROR"}
 ```
 
-
 ### https
 
 When it is desired to use TLS for increased security, flagD can be started with the following cert and key information.
@@ -127,46 +171,18 @@ When it is desired to use TLS for increased security, flagD can be started with
 This enables you to use an upgraded connection for the previous example requests, such as the following:
 
 ```
-$ curl -X POST "https://localhost:8013/flags/myBoolFlag/resolve/boolean"
+curl -X POST "https://localhost:8013/flags/myBoolFlag/resolve/boolean"
 // {"value":true,"reason":"STATIC","variant":"on"}
 ```
 
 ## Multiple source example
-Multiple providers can be supplied as the following:
-```
-./flagd start -f config/samples/example_flags.json -f config/samples/example_flags_secondary.json --service-provider http --sync-provider filepath
-```
-In case of collision between flags definition the priority goes to the later (e.g. example_flags < example_flags_secondary).
-
-
-## Installation
-
-### [Configuration](./docs/configuration.md)
-
-### Systemd
 
-To install as a systemd service run `sudo make install` this will place the binary by default in `/usr/local/bin`
-
-There will also be a default provider and sync enabled ( http / filepath ) both of which can be modified in the flagd.service.
-
-Validation can be run with `systemctl status flagd`
-And result similar to below will be seen
+Multiple providers can be supplied as the following:
 
 ```
-● flagd.service - "A generic feature flag daemon"
-     Loaded: loaded (/etc/systemd/system/flagd.service; disabled; vendor preset: enabled)
-     Active: active (running) since Mon 2022-05-30 12:19:55 BST; 5min ago
-   Main PID: 64610 (flagd)
-      Tasks: 7 (limit: 4572)
-     Memory: 1.4M
-     CGroup: /system.slice/flagd.service
-             └─64610 /usr/local/bin/flagd start -f=/etc/flagd/flags.json
-
-May 30 12:19:55 foo systemd[1]: Started "A generic feature flag daemon".
+./flagd start -f config/samples/example_flags.json -f config/samples/example_flags_secondary.json --service-provider http --sync-provider filepath
 ```
 
-### Running in a container
-
 1. `IMG=flagd-local make docker-build`
 2. `docker run -p 8013:8013 -it flagd-local start --uri ./examples/example_flags.json`
 
@@ -177,10 +193,11 @@ in the body of a flag evaluation call is processed by the JsonLogic rule to dete
 If this result is `null` or an invalid (undefined) variant then the default variant is returned.
 
 JsonLogic provides a [playground](https://jsonlogic.com/play.html) for evaluating your rules against data.
- 
+
 <u>Example</u>
 
 A flag is defined as such:
+
 ```json
 {
   "flags": {
@@ -196,9 +213,7 @@ A flag is defined as such:
           {
             "==": [
               {
-                "var": [
-                  "color"
-                ]
+                "var": ["color"]
               },
               "yellow"
             ]
@@ -215,20 +230,25 @@ A flag is defined as such:
 The rule provided returns `"on"` if `var color == "yellow"` and `"off"` otherwise:
 
 ```shell
-$ curl -X POST "localhost:8013/flags/isColorYellow/resolve/boolean" -d '{"color": "yellow"}'
+curl -X POST "localhost:8013/flags/isColorYellow/resolve/boolean" -d '{"color": "yellow"}'
 ```
+
 returns
+
 ```json
-{"value":true,"reason":"TARGETING_MATCH","variant":"on"}
+{ "value": true, "reason": "TARGETING_MATCH", "variant": "on" }
 ```
 
-whereas 
+whereas
+
 ```shell
-$ curl -X POST "localhost:8013/flags/isColorYellow/resolve/boolean" -d '{"color": "white"}'
+curl -X POST "localhost:8013/flags/isColorYellow/resolve/boolean" -d '{"color": "white"}'
 ```
+
 returns
+
 ```json
-{"value":true,"reason":"TARGETING_MATCH","variant":"off"}
+{ "value": true, "reason": "TARGETING_MATCH", "variant": "off" }
 ```
 
 ### [Reusable targeting rules](./docs/reusable_targeting_rules.md)

diff --git a/docs/high_level_architecture.md b/docs/high_level_architecture.md
@@ -0,0 +1,3 @@
+# High level architecture
+
+<img src="./images/of-flagd-0.png" width="560">
diff --git a/images/of-flagd-0.png → docs/images/of-flagd-0.png b/images/of-flagd-0.png → docs/images/of-flagd-0.png
diff --git a/docs/systemd-service.md b/docs/systemd-service.md
@@ -0,0 +1,21 @@
+# Run flagD as a systemd Service
+
+To install as a systemd service clone the repo and run `sudo make install`. This will place the binary by default in `/usr/local/bin`.
+
+There will also be a default provider and sync enabled ( http / filepath ) both of which can be modified in the flagd.service.
+
+Validation can be run with `systemctl status flagd`
+And result similar to below will be seen
+
+```
+  flagd.service - "A generic feature flag daemon"
+     Loaded: loaded (/etc/systemd/system/flagd.service; disabled; vendor preset: enabled)
+     Active: active (running) since Mon 2022-05-30 12:19:55 BST; 5min ago
+   Main PID: 64610 (flagd)
+      Tasks: 7 (limit: 4572)
+     Memory: 1.4M
+     CGroup: /system.slice/flagd.service
+             └─64610 /usr/local/bin/flagd start -f=/etc/flagd/flags.json
+
+May 30 12:19:55 foo systemd[1]: Started "A generic feature flag daemon".
+```