diff --git a/website/docs/sdks/unleash-proxy.md b/website/docs/sdks/unleash-proxy.md index 71eaeb27c5..f3dd2d503d 100644 --- a/website/docs/sdks/unleash-proxy.md +++ b/website/docs/sdks/unleash-proxy.md @@ -6,7 +6,9 @@ title: 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. :::tip + Looking for how to run the Unleash proxy? Check out the [_How to run the Unleash Proxy_ guide](../how-to/how-to-run-the-unleash-proxy.mdx)! + ::: 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 @@ -26,40 +28,51 @@ _The Unleash Proxy uses the Unleash SDK and exposes a simple API_. The Proxy wil ## Configuration :::info + You **must configure** these three variables for the proxy to start successfully: + - `unleashUrl` / `UNLEASH_URL` - `unleashApiToken` / `UNLEASH_API_TOKEN` - `clientKeys` / `UNLEASH_PROXY_CLIENT_KEYS` + ::: The Proxy has a large number of configuration options that you can use to adjust it to your specific use case. The table below lists all the available options. -| Option | Environment Variable | Default value | Required | Description | -|------------------------|----------------------------------|--------------------|:--------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `clientKeys` | `UNLEASH_PROXY_CLIENT_KEYS` | n/a | yes | List of [client keys](../reference/api-tokens-and-client-keys.mdx#proxy-client-keys) that the proxy should accept. When querying the proxy, Proxy SDKs must set the request's _client keys header_ to one of these values. The default client keys header is `Authorization`. When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. | -| | | | | | -| `clientKeysHeaderName` | `CLIENT_KEY_HEADER_NAME` | `"authorization"` | no | The name of the HTTP header to use for client keys. Incoming requests must set the value of this header to one of the Proxy's `clientKeys` to be authorized successfully. | -| `customStrategies` | `UNLEASH_CUSTOM_STRATEGIES_FILE` | `[]` | no | Use this option to inject implementation of custom activation strategies. If you are using `UNLEASH_CUSTOM_STRATEGIES_FILE`: provide a valid path to a JavaScript file which exports an array of custom activation strategies. | -| `enableOAS` | `ENABLE_OAS` | `false` | no | Set to `true` to expose the proxy's OpenAPI spec at `/docs/openapi.json` and an interactive Swagger interface at `/docs/openapi`. Read more in the [OpenAPI section](#openapi).| -| `environment` | `UNLEASH_ENVIRONMENT` | `undefined` | no | If set this will be the `environment` used by the proxy in the Unleash Context. It will not be possible for proxy SDKs to override the environment if set. | -| `logLevel` | `LOG_LEVEL ` | `"warn"` | no | Used to set `logLevel`. Supported options: `"debug"`, `"info"`, `"warn"`, `"error"` and `"fatal"` | -| `logger` | n/a | `SimpleLogger` | no | Register a custom logger. | -| `metricsInterval` | `UNLEASH_METRICS_INTERVAL` | `30000` | no | How often the proxy should send usage metrics back to Unleash, defined in ms. | -| `namePrefix` | `UNLEASH_NAME_PREFIX` | `undefined` | no | If set, the Proxy will only fetch toggles whose name start with the provided prefix. | -| `projectName` | `UNLEASH_PROJECT_NAME` | `undefined` | no | If set, the Proxy will only fetch toggles belonging to the project with this ID. | -| `proxyBasePath` | `PROXY_BASE_PATH` | `""` | no | The base path to run the proxy from. "/proxy" will be added at the end. For instance, if `proxyBasePath` is `"base/path"`, the proxy will run at `/base/path/proxy`. | -| `proxyPort` | `PORT` | `3000` | no | The port to run the proxy on. | -| `proxySecrets` | `UNLEASH_PROXY_SECRETS` | n/a | no | Deprecated alias for `clientKeys`. Please use `clientKeys` instead. | -| `refreshInterval` | `UNLEASH_FETCH_INTERVAL` | `5000` | no | How often the proxy should query Unleash for updates, defined in ms. | -| `tags` | `UNLEASH_TAGS` | `undefined` | no | If set, the proxy will only fetch feature toggles with these [tags](../advanced/tags.md). The format should be `tagName:tagValue,tagName2:tagValue2` | -| `trustProxy` | `TRUST_PROXY ` | `false` | no | If enabled, the Unleash Proxy will know that it is itself sitting behind a proxy and that the `X-Forwarded-*` header fields (which otherwise may be easily spoofed) can be trusted. The proxy will automatically enrich the IP address in the Unleash Context. Can be `true/false` (trust all proxies) or a string (trust only given IP/CIDR (e.g. `'127.0.0.1'`)). If it is a string, it can also be a list of comma separated values (e.g. `'127.0.0.1,192.168.1.1/24'` | -| `unleashApiToken` | `UNLEASH_API_TOKEN` | n/a | yes | The [client API token](../reference/api-tokens-and-client-keys.mdx#client-tokens) for connecting to Unleash API. | -| `unleashAppName` | `UNLEASH_APP_NAME` | `"unleash-proxy" ` | no | The application name to use when registering with Unleash | -| `unleashInstanceId` | `UNLEASH_INSTANCE_ID` | auto-generated | no | A unique(-ish) identifier for your instance. Typically a hostname, pod id or something similar. Unleash uses this to separate metrics from the client SDKs with the same `unleashAppName`. | -| `unleashUrl` | `UNLEASH_URL` | n/a | yes | The API URL of the Unleash instance you want to connect to. | +| Option | Environment Variable | Default value | Required | Description | +| --- | --- | --- | :-: | --- | +| `clientKeys` | `UNLEASH_PROXY_CLIENT_KEYS` | n/a | yes | List of [client keys](../reference/api-tokens-and-client-keys.mdx#proxy-client-keys) that the proxy should accept. When querying the proxy, Proxy SDKs must set the request's _client keys header_ to one of these values. The default client keys header is `Authorization`. When using an environment variable to set the proxy secrets, the value should be a comma-separated list of strings, such as `secret-one,secret-two`. | +| `clientKeysHeaderName` | `CLIENT_KEY_HEADER_NAME` | `"authorization"` | no | The name of the HTTP header to use for client keys. Incoming requests must set the value of this header to one of the Proxy's `clientKeys` to be authorized successfully. | +| `customStrategies` | `UNLEASH_CUSTOM_STRATEGIES_FILE` | `[]` | no | Use this option to inject implementation of custom activation strategies. If you are using `UNLEASH_CUSTOM_STRATEGIES_FILE`: provide a valid path to a JavaScript file which exports an array of custom activation strategies. | +| `enableOAS` | `ENABLE_OAS` | `false` | no | Set to `true` to expose the proxy's OpenAPI spec at `/docs/openapi.json` and an interactive Swagger interface at `/docs/openapi`. Read more in the [OpenAPI section](#openapi). | +| `environment` | `UNLEASH_ENVIRONMENT` | `undefined` | no | If set this will be the `environment` used by the proxy in the Unleash Context. It will not be possible for proxy SDKs to override the environment if set. | +| `logLevel` | `LOG_LEVEL ` | `"warn"` | no | Used to set `logLevel`. Supported options: `"debug"`, `"info"`, `"warn"`, `"error"` and `"fatal"` | +| `logger` | n/a | `SimpleLogger` | no | Register a custom logger. | +| `metricsInterval` | `UNLEASH_METRICS_INTERVAL` | `30000` | no | How often the proxy should send usage metrics back to Unleash, defined in ms. | +| `namePrefix` | `UNLEASH_NAME_PREFIX` | `undefined` | no | If set, the Proxy will only fetch toggles whose name start with the provided prefix. | +| `projectName` | `UNLEASH_PROJECT_NAME` | `undefined` | no | If set, the Proxy will only fetch toggles belonging to the project with this ID. | +| `proxyBasePath` | `PROXY_BASE_PATH` | `""` | no | The base path to run the proxy from. "/proxy" will be added at the end. For instance, if `proxyBasePath` is `"base/path"`, the proxy will run at `/base/path/proxy`. | +| `proxyPort` | `PORT` | `3000` | no | The port to run the proxy on. | +| `proxySecrets` | `UNLEASH_PROXY_SECRETS` | n/a | no | Deprecated alias for `clientKeys`. Please use `clientKeys` instead. | +| `refreshInterval` | `UNLEASH_FETCH_INTERVAL` | `5000` | no | How often the proxy should query Unleash for updates, defined in ms. | +| `tags` | `UNLEASH_TAGS` | `undefined` | no | If set, the proxy will only fetch feature toggles with these [tags](../advanced/tags.md). The format should be `tagName:tagValue,tagName2:tagValue2` | +| `trustProxy` | `TRUST_PROXY ` | `false` | no | If enabled, the Unleash Proxy will know that it is itself sitting behind a proxy and that the `X-Forwarded-*` header fields (which otherwise may be easily spoofed) can be trusted. The proxy will automatically enrich the IP address in the Unleash Context. Can be `true/false` (trust all proxies) or a string (trust only given IP/CIDR (e.g. `'127.0.0.1'`)). If it is a string, it can also be a list of comma separated values (e.g. `'127.0.0.1,192.168.1.1/24'` | +| `unleashApiToken` | `UNLEASH_API_TOKEN` | n/a | yes | The [client API token](../reference/api-tokens-and-client-keys.mdx#client-tokens) for connecting to Unleash API. | +| `unleashAppName` | `UNLEASH_APP_NAME` | `"unleash-proxy" ` | no | The application name to use when registering with Unleash | +| `unleashInstanceId` | `UNLEASH_INSTANCE_ID` | auto-generated | no | A unique(-ish) identifier for your instance. Typically a hostname, pod id or something similar. Unleash uses this to separate metrics from the client SDKs with the same `unleashAppName`. | +| `unleashUrl` | `UNLEASH_URL` | n/a | yes | The API URL of the Unleash instance you want to connect to. | +## Privacy and hosting options {#privacy-and-hosting} + +
+ +The Unleash Proxy is important because you should not expose your entire set of toggle configurations to your end users. Single page apps work in the context of a specific user. The proxy allows you to only provide data that relates to that one user: _The proxy will only return the evaluated toggles (with variants) that should be enabled for that specific user in that specific context._ + +Most of our customers prefer to run the Unleash proxy themselves. We actually prefer this as we don’t want to see your users. Running it is pretty simple, it is either a small Node.js process you start or a docker image you use. (We can of course host the proxy for you also.) + +For more information on the various hosting options and their tradeoffs, refer to the [proxy hosting strategies topic document](../topics/proxy-hosting.mdx). ## Health endpoint @@ -81,12 +94,12 @@ Connection: keep-alive Keep-Alive: timeout=5 ``` - ## Custom activation strategies The Unleash Proxy can load [custom activation strategies](../advanced/custom-activation-strategy.md) for front-end client SDKs ([Android](../sdks/android-proxy.md), [JavaScript](../sdks/proxy-javascript.md), [React](../sdks/proxy-react.md), [iOS](../sdks/proxy-ios.md)). For a step-by-step guide, refer to the [_how to use custom strategies_ guide](../how-to/how-to-use-custom-strategies.md#step-3-b). To load custom strategies, use either of these two options: + - the **`customStrategies`** option: use this if you're running the Unleash Proxy via Node directly. - the **`UNLEASH_CUSTOM_STRATEGIES_FILE`** environment variable: use this if you're running the proxy as a container. @@ -98,7 +111,7 @@ Each strategy file must export a list of instantiated strategies. A file can exp Here's an example file that exports two custom strategies: -``` js +```js const { Strategy } = require('unleash-client'); class MyCustomStrategy extends Strategy { @@ -110,10 +123,7 @@ class MyOtherCustomStrategy extends Strategy { } // export strategies -module.exports = [ - new MyCustomStrategy(), - new MyOtherCustomStrategy() -]; +module.exports = [new MyCustomStrategy(), new MyOtherCustomStrategy()]; ``` Refer the [custom activation strategy documentation](../advanced/custom-activation-strategy.md#implementation) for more details on how to implement a custom activation strategy. @@ -126,8 +136,10 @@ The Unleash Proxy has a very simple API. It takes the [Unleash Context](../user_ ### OpenAPI integration and API documentation {#openapi} -:::info Availability -The OpenAPI integration is available in versions 0.9 and later of the Unleash proxy. +:::info + +Availability The OpenAPI integration is available in versions 0.9 and later of the Unleash proxy. + ::: The proxy can optionally expose a runtime-generated OpenAPI JSON spec and a corresponding OpenAPI UI for its API. The OpenAPI UI page is an interactive page where you can discover and test the API endpoints the proxy exposes. The JSON spec can be used to generate an OpenAPI client with OpenAPI tooling such as the [OpenAPI generator](https://openapi-generator.tech/). @@ -140,7 +152,6 @@ The spec and UI can then be found at `/docs/openapi.json` and ` + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/website/static/img/proxy-hosting-customer-multi.svg b/website/static/img/proxy-hosting-customer-multi.svg new file mode 100644 index 0000000000..85cbabfc36 --- /dev/null +++ b/website/static/img/proxy-hosting-customer-multi.svg @@ -0,0 +1,212 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/website/static/img/proxy-hosting-customer-single.svg b/website/static/img/proxy-hosting-customer-single.svg new file mode 100644 index 0000000000..60cfb1dbd6 --- /dev/null +++ b/website/static/img/proxy-hosting-customer-single.svg @@ -0,0 +1,158 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/website/static/img/proxy-hosting-unleash-api-customer-proxy.svg b/website/static/img/proxy-hosting-unleash-api-customer-proxy.svg new file mode 100644 index 0000000000..22348e65f6 --- /dev/null +++ b/website/static/img/proxy-hosting-unleash-api-customer-proxy.svg @@ -0,0 +1,159 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +