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 provides a way for you to consume feature toggles in front-end clients, such as the JavaScript Proxy client and React Proxy client.
Depending on your setup, the Proxy is most easily run in one of two ways, depending on your situation:
If you're using a hosted version of Unleash, we can also run the proxy for you.
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 for the proxy to use.
- If you're running the Proxy via Docker: the
docker
command line tool. - If you're running the Proxy as a Node.js app: Node.js and its command line tools.
- A Proxy client key. This can be any arbitrary string (for instance:
proxy-client-key
). Use this key when connecting a client SDK to the Proxy.
We provide a Docker image (available on on Docker Hub) that you can use to run the proxy.
Use the docker
command to pull the Proxy image:
docker pull unleashorg/unleash-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.
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:
Unleash-proxy is listening on port 3000!
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.
If you don't already have an existing Node.js project, create one:
npm init
Install the Unleash Proxy as a dependency:
npm install @unleash/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.
Here is an example of what running the Proxy as a Node.js app might look like:
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`),
);
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.