mirror of
https://github.com/Unleash/unleash.git
synced 2024-10-18 20:09:08 +02:00
d5fbd0b743
## What This (admittedly massive) PR updates the "physical" documentation structure and fixes url inconsistencies and SEO problems reported by marketing. The main points are: - remove or move directories : advanced, user_guide, deploy, api - move the files contained within to the appropriate one of topics, how-to, tutorials, or reference - update internal doc links and product links to the content - create client-side redirects for all the urls that have changed. A number of the files have been renamed in small ways to better match their url and to make them easier to find. Additionally, the top-level api directory has been moved to /reference/api/legacy/unleash (see the discussion points section for more on this). ## Why When moving our doc structure to diataxis a while back, we left the "physical' files lying where they were, because it didn't matter much to the new structure. However, that did introduce some inconsistencies with where you place docs and how we organize them. There's also the discrepancies in whether urls us underscores or hyphens (which isn't necessarily the same as their file name), which has been annoying me for a while, but now has also been raised by marketing as an issue in terms of SEO. ## Discussion points The old, hand-written API docs have been moved from /api to /reference/api/legacy/unleash. There _is_ a /reference/api/unleash directory, but this is being populated by the OpenAPI plugin, and mixing those could only cause trouble. However, I'm unsure about putting /legacy/ in the title, because the API isn't legacy, the docs are. Maybe we could use another path? Like /old-docs/ or something? I'd appreciate some input on this.
113 lines
4.3 KiB
Plaintext
113 lines
4.3 KiB
Plaintext
---
|
|
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](../reference/unleash-proxy.md) provides a way for you to consume feature toggles in [front-end clients](../reference/sdks/index.md#front-end-sdks), such as the [JavaScript Proxy client](../reference/sdks/javascript-browser.md) and [React Proxy client](../reference/sdks/react.md).
|
|
|
|
Depending on your setup, the Proxy is most easily run in one of two ways, depending on your situation:
|
|
|
|
- [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.
|
|
|
|
## Prerequisites
|
|
|
|
This is what you need before you can run the proxy:
|
|
|
|
- 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 {#run-proxy-via-docker}
|
|
|
|
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
|
|
|
|
Use the `docker` command to pull the Proxy image:
|
|
|
|
```bash title="Pull the Unleash Proxy docker image"
|
|
docker pull unleashorg/unleash-proxy
|
|
```
|
|
|
|
### 2. Start the Proxy
|
|
|
|
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](../reference/unleash-proxy.md#configuration-options).
|
|
|
|
```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
|
|
```
|
|
|
|
If the proxy starts up successfully, you should see the following output:
|
|
|
|
```bash
|
|
Unleash-proxy is listening on port 3000!
|
|
```
|
|
|
|
## How to run the Proxy as a Node.js app {#run-proxy-as-node-app}
|
|
|
|
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.
|
|
|
|
### 1. initialize the project
|
|
|
|
If you don't already have an existing Node.js project, create one:
|
|
|
|
```bash npm2yarn
|
|
npm init
|
|
```
|
|
|
|
### 2. Install the Unleash Proxy package
|
|
|
|
Install the Unleash Proxy as a dependency:
|
|
|
|
```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](../reference/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: '<unleash-api-url>',
|
|
unleashApiToken: '<client-api-token>',
|
|
clientKeys: ['<proxy-client-key>'],
|
|
proxyPort: 3000,
|
|
// highlight-end
|
|
});
|
|
|
|
app.listen(port, () =>
|
|
console.log(`Unleash Proxy listening on http://localhost:${port}/proxy`),
|
|
);
|
|
```
|
|
|
|
## 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="proxy" endpointType="proxy" title="Request toggles from the Unleash Proxy"/>
|