From 57c14c7565f31e9abc752b447df472cb036cf51f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ivar=20Conradi=20=C3=98sthus?= Date: Fri, 4 Jun 2021 13:44:34 +0200 Subject: [PATCH] fix: add details about the proxy --- websitev2/docs/deploy/email.md | 3 +- websitev2/docs/deploy/getting-started.md | 4 +- websitev2/docs/sdks/index.md | 7 +- websitev2/docs/sdks/unleash-proxy.md | 100 +++++++++++++++++++++-- websitev2/docs/user_guide/index.md | 7 +- 5 files changed, 106 insertions(+), 15 deletions(-) diff --git a/websitev2/docs/deploy/email.md b/websitev2/docs/deploy/email.md index 21936baa5e..e74884ff1a 100644 --- a/websitev2/docs/deploy/email.md +++ b/websitev2/docs/deploy/email.md @@ -8,7 +8,8 @@ New since Unleash v4.0.0 is an email service allowing us to send reset password If the service is not configured you'll see a log line every time you add a new user saying ```bash -[2021-05-07T12:59:04.572] [WARN] routes/user-controller.ts - email was not sent to the user because email configuration is lacking +[2021-05-07T12:59:04.572] [WARN] routes/user-controller.ts - email +was not sent to the user because email configuration is lacking ``` ## Configuring {#configuring} diff --git a/websitev2/docs/deploy/getting-started.md b/websitev2/docs/deploy/getting-started.md index 366c5291b9..acecc927be 100644 --- a/websitev2/docs/deploy/getting-started.md +++ b/websitev2/docs/deploy/getting-started.md @@ -116,7 +116,9 @@ docker run -p 4242:4242 \ Once the Unleash server has started, go to [localhost:4242](http://localhost:4242) in your browser. If you see an empty list of feature toggles, try creating one with [curl](https://curl.se/) from a terminal/bash shell: ``` -curl --location -H "Authorization: " --request POST 'http://localhost:4242/api/admin/features' --header 'Content-Type: application/json' --data-raw '{\ +curl --location -H "Authorization: " \ + --request POST 'http://localhost:4242/api/admin/features' \ + --header 'Content-Type: application/json' --data-raw '{\ "name": "Feature.A",\ "description": "Dolor sit amet.",\ "type": "release",\ diff --git a/websitev2/docs/sdks/index.md b/websitev2/docs/sdks/index.md index ceb7d338ae..ecf8f19e7f 100644 --- a/websitev2/docs/sdks/index.md +++ b/websitev2/docs/sdks/index.md @@ -7,7 +7,7 @@ In order to connect your application to Unleash you need to use a client SDK (so On this page you will find examples for connecting your application to the demo instance. If you are connecting to your own private instance you will have to remember to replace the `API token` and the `API url` given in the examples. -We have examples for all _official client SDKs_: +**Official Server SDKs**: - [Java SDK](./java_sdk) - [Node.js SDK](./node_sdk) @@ -15,7 +15,10 @@ We have examples for all _official client SDKs_: - [Ruby SDK](./ruby_sdk) - [Python SDK](./python_sdk) - [.Net SDK](./dot_net_sdk) -- [Javascript SDK](./proxy-javascript) (Used by single-page applications) + +**Official Frontend Proxy SDKs:** + +- [Javascript SDK](./proxy-javascript) - Android SDK (coming soon) - iOS SDK (coming soon) diff --git a/websitev2/docs/sdks/unleash-proxy.md b/websitev2/docs/sdks/unleash-proxy.md index 711a3e45e2..239071371c 100644 --- a/websitev2/docs/sdks/unleash-proxy.md +++ b/websitev2/docs/sdks/unleash-proxy.md @@ -1,9 +1,11 @@ --- id: unleash-proxy -title: The Unleash Proxy +title: Unleash Proxy --- -A lot of our users wanted to use feature toggles in their single-page and native applications. To solve this in a performant and privacy concerned way we built The Unleash Proxy +> The unleash-proxy is compatible with all Unleash Enterprise versions and Unleash Open-Source v4. You should reach out to **support@getunleash.io** if you want the Unleash Team to host the Unleash Proxy for you. + +A lot of our users wanted to use feature toggles in their single-page and native applications. To solve this in a preformat and privacy concerned way we built The Unleash Proxy The Unleash Proxy sits between the Unleash API and the application. It provides a simple and super-fast API, as it has all the data it needs available in memory. @@ -15,11 +17,95 @@ The proxy solves three important aspects: ![The Unleash Proxy](/img/The-unleash-proxy.png) -_The Unleash-Proxy uses the Unleash SDK and exposes a simple API_. The Proxy will synchronize with the Unleash API in the background and provide a simple HTTP API for clients. +_The Unleash Proxy uses the Unleash SDK and exposes a simple API_. The Proxy will synchronize with the Unleash API in the background and provide a simple HTTP API for clients. + +### How to Run the Unleash Proxy + +The Unleash Proxy is Open Source and [available on github](https://github.com/Unleash/unleash-proxy). You can either run it as a docker image or as part of a [node.js express application](https://github.com/Unleash/unleash-proxy#run-with-nodejs). + +The easies way to run Unleash is via Docker. We have published a [docker image on docker hub](https://hub.docker.com/r/unleashorg/unleash-proxy). + +**Step 1: Pull** + +```bash +docker pull docker pull unleashorg/unleash-proxy +``` + +**Step 2: Start** + +```bash +docker run \ + -e UNLEASH_PROXY_SECRETS=some-secret \ + -e UNLEASH_URL='https://app.unleash-hosted.com/demo/api/' \ + -e UNLEASH_API_TOKEN=56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d \ + -p 3000:3000 \ + unleashorg/unleash-proxy +``` + +You should see the following output: + +```bash +Unleash-proxy is listening on port 3000! +``` + +**Step 3: verify** + +In order to verify the proxy you can use curl and see that you get a few evaluated feature toggles back: + +```bash +curl http://localhost:3000/proxy -H "Authorization: some-secret" +``` + +Expected output would be something like: + +```json +{ + "toggles": [ + { + "name": "demo", + "enabled": true, + "variant": { + "name": "disabled", + "enabled": false + } + }, + { + "name": "demoApp.step1", + "enabled": true, + "variant": { + "name": "disabled", + "enabled": false + } + } + ] +} +``` + +**Health endpoint** + +The proxy will try to synchronize with the Unleash API at startup, until it has successfully done that the proxy will return `HTTP 503 - Not Read?` for all request. You can use the health endpoint to validate that the proxy is ready to recieve requests: + +```bash +curl curl http://localhost:3000/proxy/health -I +``` + +```bash +HTTP/1.1 200 OK +Access-Control-Allow-Origin: * +Access-Control-Expose-Headers: ETag +Content-Type: text/html; charset=utf-8 +Content-Length: 2 +ETag: W/"2-eoX0dku9ba8cNUXvu/DyeabcC+s" +Date: Fri, 04 Jun 2021 10:38:27 GMT +Connection: keep-alive +Keep-Alive: timeout=5 +``` + +There are multiple more configuration options available. You find all [available options on github](https://github.com/Unleash/unleash-proxy#available-options). ### Unleash Proxy API {#unleash-proxy-api} -The Unleash-Proxy has a very simple API. It takes the [Unleash Context](../user_guide/unleash_context) as input and will return the feature toggles relevant for that specific context. +The Unleash Proxy has a very simple API. It takes the [Unleash Context](../user_guide/unleash_context) as input and will return the feature toggles relevant for that specific context. ![The Unleash Proxy](/img/The-Unleash-Proxy-API.png). @@ -36,11 +122,9 @@ The Unleash Proxy takes the heavy lifting of evaluating toggles and only returns However in some settings you would like a bit more logic around it to make it as fast as possible, and keep up to date with changes. - [JavaScript Proxy SDK](./proxy-javascript) -- React SDK (coming soon) -- React Native SDK (coming soon) - Android Proxy SDK (coming soon) - iOS Proxy SDK (coming soon) +- React SDK (coming soon) +- React Native SDK (coming soon) The proxy is also ideal fit for serverless functions such as AWS Lambda. In that scenario the proxy can run on a small container near the serverless function, preferably in the same VPC, giving the lambda extremely fast access to feature flags, at a predictable cost. - -The unleash-proxy is compatible with unleash-enterprise and is offered as a free add-on to all our customers. We can also host it for you, for a small fee covering our cost. diff --git a/websitev2/docs/user_guide/index.md b/websitev2/docs/user_guide/index.md index c84914ce7c..f61359b09c 100644 --- a/websitev2/docs/user_guide/index.md +++ b/websitev2/docs/user_guide/index.md @@ -16,16 +16,17 @@ We recommend that you read about [our unique architecture](https://www.unleash-h Before you can connect your application to Unleash you need a Unleash server. You have a few options available. 1. [Unleash Open-source - Self-managed](deploy/getting_started) -2. [Unleash Enterprise - Cloud-hosted](https://www.unleash-hosted.com) -3. [Unleash Enterprise - Self-hosted](https://www.unleash-hosted.com) +2. [Unleash Enterprise - Cloud-hosted](https://www.getunleash.io) +3. [Unleash Enterprise - Self-hosted](https://www.getunleash.io) ## System Overview {#system-overview} -Unleash is composed of three parts: +Unleash is composed of the following parts: - **Unleash API** - The service holding all feature toggles and their configurations. Configurations declare which activation strategies to use and which parameters they should get. - **Unleash UI** - The dashboard used to manage feature toggles, define new strategies, look at metrics, etc. - **Unleash SDK** - Used by clients to check if a feature is enabled or disabled. The SDK also collects metrics and sends them to the Unleash API. Activation Strategies are also implemented in the SDK. +- **Unleash Proxy** - Sits between frontend and native applications and the Unleash API. Ensures high performance and that we don't expose the full feature toggle configuration to end-users. [Read more about Unleash Proxy](/sdks/unleash-proxy) ![system_overview](/img/unleash-diagram.png 'System Overview')