From 5e382e64dcd5742430e2771f48942c4dfc109d57 Mon Sep 17 00:00:00 2001 From: Thomas Heartman Date: Wed, 13 Apr 2022 15:06:42 +0200 Subject: [PATCH] docs: api request and placeholders to proxy how-to --- .../how-to/how-to-run-the-unleash-proxy.mdx | 124 ++++++++++-------- 1 file changed, 72 insertions(+), 52 deletions(-) diff --git a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx index 300bd16afb..642d7eb256 100644 --- a/website/docs/how-to/how-to-run-the-unleash-proxy.mdx +++ b/website/docs/how-to/how-to-run-the-unleash-proxy.mdx @@ -1,88 +1,108 @@ --- title: How to run the Unleash Proxy --- +import ApiRequest from '@site/src/components/ApiRequest' + +:::info Placeholders +Placeholders in the code samples below are delimited by angle brackets (i.e. ``). You will need to replace them with the values that are correct in _your_ situation for the code samples to run properly. +::: + The [Unleash Proxy](../sdks/unleash-proxy.md) provides a way for you to consume feature toggles in [front-end clients](../sdks/index.md#front-end-sdks), such as the [JavaScript Proxy client](../sdks/proxy-javascript.md) and [React Proxy client](../sdks/proxy-react.md). Depending on your setup, the Proxy is most easily run in one of two ways, depending on your situation: -- Run the proxy via Docker -- Run the proxy as a Node.js app +- [Via Docker](#run-proxy-via-docker) +- [As a Node.js app](#run-proxy-as-node-app) -If you're using a hosted version of Unleash, we can also run the proxy for you if you'd rather not run it yourself. +If you're using a hosted version of Unleash, we can also run the proxy for you. ## Prerequisites -This is what you need to do before you can run the proxy +This is what you need before you can run the proxy: -- A running Unleash server to connect to -- A client API token for the proxy to use. -- if you're running the Proxy via Docker: [the `docker` command line tool](https://www.docker.com/) +- A running Unleash server to connect to. You'll need its API path (e.g. `https://app.unleash-hosted.com/demo/api`) to connect the proxy to it. +- A [client API token](../reference/api-tokens-and-client-keys#client-tokens) for the proxy to use. +- If you're running the Proxy via Docker: [the `docker` command line tool](https://www.docker.com/). - If you're running the Proxy as a Node.js app: [Node.js and its command line tools](https://nodejs.org/). +- A [Proxy client key](../reference/api-tokens-and-client-keys#proxy-client-keys). This can be any arbitrary string (for instance: `proxy-client-key`). Use this key when connecting a client SDK to the Proxy. -## How to run the Proxy via Docker +## How to run the Proxy via Docker {#run-proxy-via-docker} -The easiest way to run Unleash is via Docker. We have published a [docker image on docker hub](https://hub.docker.com/r/unleashorg/unleash-proxy). +We provide a [Docker image (available on on Docker Hub)](https://hub.docker.com/r/unleashorg/unleash-proxy) that you can use to run the proxy. ### 1. Pull the Proxy image - ```bash - docker pull unleashorg/unleash-proxy - ``` +Use the `docker` command to pull the Proxy image: -### 2. Start the proxy +```bash title="Pull the Unleash Proxy docker image" +docker pull unleashorg/unleash-proxy +``` - ```bash - docker run \ - -e UNLEASH_PROXY_CLIENT_KEYS=some-secret \ - -e UNLEASH_URL='https://app.unleash-hosted.com/demo/api/' \ - -e UNLEASH_API_TOKEN=56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d \ - -p 3000:3000 \ - unleashorg/unleash-proxy - ``` +### 2. Start the Proxy -You should see the following output: +When running the Proxy, you'll need to provide it with at least the configuration options listed below. Check the reference docs for the [full list of configuration options](../sdks/unleash-proxy.md#configuration-options). - ```bash - Unleash-proxy is listening on port 3000! - ``` +```bash title="Run the Unleash Proxy via Docker" +docker run \ + -e UNLEASH_PROXY_CLIENT_KEYS= \ + -e UNLEASH_URL='' \ + -e UNLEASH_API_TOKEN= \ + -p 3000:3000 \ + unleashorg/unleash-proxy +``` -## How to run the Proxy as a Node.js app +If the proxy starts up successfully, you should see the following output: -To run the Proxy via Node.js, you'll have to create your own Node.js project and use the Unleash Proxy as a dependency. Assuming you've already set up your project, here's the steps to take to start the proxy as part of your app: +```bash +Unleash-proxy is listening on port 3000! +``` -### 1. Install the Unleash Proxy package +## How to run the Proxy as a Node.js app {#run-proxy-as-node-app} - ``` shell npm2yarn - npm install @unleash/proxy - ``` +To run the Proxy via Node.js, you'll have to create your own Node.js project and use the Unleash Proxy as a dependency. -### 2. Initialize and start the proxy in your code. +### 1. initialize the project -A fully working sample app that uses the proxy: +If you don't already have an existing Node.js project, create one: - ``` js - const port = 3000; +``` bash npm2yarn +npm init +``` - const { createApp } = require('@unleash/proxy'); +### 2. Install the Unleash Proxy package - const app = createApp({ - unleashUrl: 'https://app.unleash-hosted.com/demo/api/', - unleashApiToken: '56907a2fa53c1d16101d509a10b78e36190b0f918d9f122d', - clientKeys: ['some-secret', 'another-proxy-secret', 's1'], - refreshInterval: 1000, - }); +Install the Unleash Proxy as a dependency: - app.listen(port, () => - console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`), - ); - ``` +``` shell npm2yarn +npm install @unleash/proxy +``` + +### 3. Configure and start the proxy + +Import the `createApp` function from `@unleash/proxy` and configure the proxy. You'll need to provide at least the configuration options highlighted below. Check the reference docs for the [full list of configuration options](../sdks/unleash-proxy.md#configuration-options). + +Here is an example of what running the Proxy as a Node.js app might look like: + +``` js title="Sample app running the Unleash Proxy" +const port = 3000; + +const { createApp } = require('@unleash/proxy'); + +const app = createApp({ + // highlight-start + unleashUrl: '', + unleashApiToken: '', + clientKeys: [''], + // highlight-end +}); + +app.listen(port, () => + console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`), +); +``` ## Verify that the proxy is working -In order to verify the proxy you can use curl and see that you get a few evaluated feature toggles back. Assuming that the proxy is running on port 3000 and that your proxy client key is `some-secret`, you could run this command : +When the proxy process has started up correctly, you can start querying its `/proxy` endpoint. If it's running correctly, you'll get back a JSON object with a list of toggles. The list may be empty if you haven't added any toggles for the corresponding project/environment yet. -```bash -curl http://localhost:3000/proxy -H "Authorization: some-secret" -``` - -Check the reference docs for API return values +