docs: api request and placeholders to proxy how-to

Unleash · Apr 13, 2022 · 5e382e6 · 5e382e6
1 parent 0f9da03
commit 5e382e6
Showing 1 changed file with 71 additions and 51 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
@@ -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. `<placeholder-name>`). 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=<proxy-client-key> \
+    -e UNLEASH_URL='<unleash-api-url>' \
+    -e UNLEASH_API_TOKEN=<client-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
+```
 
-## Verify that the proxy is working
+### 3. Configure and start the proxy
 
-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 :
+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).
 
-```bash
-curl http://localhost:3000/proxy -H "Authorization: some-secret"
+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: '<unleash-api-url>',
+    unleashApiToken: '<client-api-token>',
+    clientKeys: ['<proxy-client-key>'],
+    // highlight-end
+});
+
+app.listen(port, () =>
+    console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`),
+);
 ```
 
-Check the reference docs for API return values
+## Verify that the proxy is working
+
+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.
+
+<ApiRequest verb="get" url="api/admin/projects/<project-id>/features" title="Request toggles from the Unleash Proxy"/>